bip-team / humoto Goto Github PK

Task based optimization framework

Home Page: https://bip-team.github.io/humoto/

License: Apache License 2.0

CMake 4.16% Makefile 0.35% C++ 87.26% C 0.30% TeX 7.67% MATLAB 0.26% Shell 0.01%

humoto's Introduction

This is Humoto - a software framework for manipulation of linear least-squares problems with (in)equality constraints. It supports both weighting and lexicographic prioritization and can be characterized as a tool for goal programming. However, the development was driven by works in other fields - robotics, control, and numerical optimization; for this reason our terminology and interpretations are different.

The core functionalities of Humoto are formulation of least-squares problems and their resolution with the help of various third-party software using uniform programming interfaces. However, due to our interest in robotic applications, the framework also facilitates formulation and implementation of optimization problems for control of robots, in particular, model predictive control problems. For the same reason, we pay special attention to computational performance in order to be able to employ the framework in real-time scenarios.

In addition to the core components, the distribution of Humoto includes several modules - implementations of specific controllers. The modules serve as examples of using the framework, but can also be used in accordance with their primary purpose.

@tableofcontents

Accessing Humoto {#md_readme_access}

Humoto is distributed under the terms of Apache 2.0 license, see [LICENSE](@ref LICENSE) for more information. All files are covered by the same license except those which were borrowed from other projects as indicated in [INSTALL.md](@ref md_install) file.

The source code can be obtained using git:

git clone https://github.com/bip-team/humoto

Learning Humoto {#md_readme_learn}

The framework is distributed with two kinds of documentation:

PDF manual overviews the main concepts and contains mathematical derivations. If the precompiled version is not available, you have to go to 'doc/latex' and execute 'make' to compile it.
Doxygen documentation for developers which incorporates a number of files in markdown format stored in the root and 'doc' directories. It can be compiled by calling 'make' in 'doc/doxygen' folder.

Precompiled documentation is available at https://bip-team.github.io/humoto/.

The first step is to read the introductory chapter of LaTeX documentation, then, depending on your interests, you may

learn about
- the authors from [AUTHORS.md](@ref md_authors)
- the directory layout from [doc/directory_layout.md](@ref md_directory_layout)
- dependencies and compilation of tests from file [INSTALL.md](@ref md_install)
use one of the provided modules
- you can find an example in [modules/wpg04/tests/test_000.cpp](@ref wpg04_example)
- relevant mathematical derivations can be found in the respective chapters of LaTeX documentation
modify the core or a module
- you should first read the coding policies in [doc/coding_policies.md](@ref md_coding_policies)
- then you can learn how to
  - implement new tasks [doc/howto_tasks.md](@ref md_howto_tasks)
  - add support of configuration files to your classes in [doc/howto_configurable.md](@ref md_howto_configurable)
implement your own module
- you can start by cloning a template module from https://github.com/bip-team/humoto-module-template
develop a controller for a robot using Humoto
- you can take a look at the controller for Pepper robot at https://github.com/bip-team/humoto-controller-pepper
- and clone a template controller from https://github.com/bip-team/humoto-controller-template

FAQ {#md_readme_faq}

What are the existing applications of this framework? {#md_readme_faq_applications}

Early versions of Humoto were used for walking control of HRP-4 humanoid robot. See module wpg03, its LaTeX documentation and references therein, and a video of the robot during the trials.
More recently, Humoto has been used for motion control of a humanoid robot on a wheeled base (Pepper). See modules [pepper_mpc](@ref pepper_mpc) and [pepper_ik](@ref pepper_ik) and their LaTeX documentation.

What is the difference between humoto and ... {#md_readme_faq_comparison}

RobOptim? Humoto and RobOptim were developed with one similar goal in mind: interfacing various optimization solvers in robot control applications. There are, however, many differences. Humoto cannot deal with general nonlinear problems as RobOptim does, but, unlike RobOptim, Humoto supports hierarchical (lexicographic) optimization problems. Moreover, our framework standardizes and automates formulation of optimization problems using the concept of '[task](@ref md_howto_tasks)'. Finally, we pay more attention to performance, e.g., Humoto supports more hot-starting options and provides [functionality](@ref etools) for blockwise matrix operations with sparsity support.
SOTH (SOT Hierarchical solver )? Humoto is a framework which is designed to provide common interface to various solvers, including hierarchical (lexicographic) solvers, while SOTH is a particular hierarchical solver.

Related repositories {#md_readme_relatedrepos}

https://github.com/bip-team/humoto-module-template

Template of an external module, i.e., a module which is not included in the main Humoto repository.
https://github.com/bip-team/humoto-controller-template

Template of a controller based on Humoto.
https://github.com/bip-team/humoto-controller-pepper

Controller for Pepper robot.
https://github.com/bip-team/humoto-module-wpg03-collaboration

Walking module for collaborative carrying tasks. Developed by Joven Agravante.

More information {#md_readme_faq_more}

Todo: see [doxygen todo page](@ref todo) and [doc/known_issues.md](@ref md_known_issues)
Changelog: see [CHANGELOG.md](@ref md_changelog)

humoto's People

Contributors

Stargazers

Watchers

Forkers

jordan-palacios asherikov janmichl pal-robotics-forks zdkhit

humoto's Issues

handling of time intervals

Current approach to handling of time intervals, when the same interval is often stored using separate variables in seconds and milliseconds, is unsatisfactory and must be revised. We may also want to use microseconds.

tutorial test_000 fails

After first installation of humoto with make all. test_000 returns:
./test_000
In readNestedConfig() // Failed to parse node in the configuration file: In readScalar() // Configuration file does not contain entry 'solve_two_levels_as_qp'.

Size of gh-pages branch

Project web-page branch (gh-pages) is quite heavy. Consequently, cloning and pulling (after update of gh-pages) takes time and space.

We may want to create a separate project for documentation, or find some other workaround.

optionally update configurable classes instead of resetting them

Currently, configurable classes are reset before a configuration file is read. We may want to avoid this, i.e., to set only those parameters, which are specified in the configuration file.

JSON support

Some of our collaborators use JSON format for configuration files. It may be a good idea to add support for this format in Humoto.

linker flags

Guys, I guess the problem that you have is that you are not using GNU linker on MAC OS. Note that "HUMOTO_SHARED_GNU_LINKER_FLAGS" was intended to be used with GNU linker only (as suggested by the name of the variable). If the linker is different, don't use these flags at all.

Ideally, we should identify the linker and set flags accordingly -- configuration must be specific to a linker, not a platform.

Separation of WPG03?

WPG03 is currently unsupported. It is unlikely that we will invest resources in its further development. This could be a good reason for creation of a separate repository for this module to reduce maintenance costs.

Replace GoogleTest with Boost.Test?

We can drop dependency on GoogleTest and use Boost.Test instead -- we already depend on Boost anyway.

Sharp changes of the angular velocity in Pepper controller

Currently, angular velocity changes abruptly, e.g., it may intantly increase from 0.0 to the given constant value. It would be nice to smooth such changes. May be even introduce additional MPC problem for rotations.

Hotstarting with precomputed factorizations

In order to enable implementation of hotstarting with precomputed factorizations we have to

keep track of modifications in the tasks
keep track of modifications in the hierarchy
store factorization of Hessian obtained on the preceding iteration

Solve hierarchies with sequences of QP's

Currently, QP solvers can only be used to solve optimization problems with two levels. We need to add support for solving hierarchies consisting of larger number of levels using sequences of QP's.

spatial algebra

Consider implementation of our own spatial vector class with basic operations.

Compilation of libraries

Currently, the compilation of the whole project is rather slow. For this reason, testing of the code may be time consuming. We can address this by compiling the core/modules to static/shared libraries.

Support of LP problems

We should investigate possibility of adding support of LP problems in the framework. They can be useful in some cases.

Better bounds on velocities in MPC for Pepper

Bounds on the translational velocities imposed in the MPC do not properly reflect the actual limitations of the wheel motors, especially when rotation is performed in addition to translation. We need to improve the bounds.

Inequality tasks on the second level + QP solver

It is possible to solve a hierarchy of two levels with inequality tasks on the second level as a QP. This can be done by introducing slack variables explicitly and pushing the inequalities to the first level. Some architectural changes are necessary for this to work: weighting of the tasks must be handled differently, handling of solution vector must be changed, etc.

We hardly need this feature, consider this issue as a note.

Communication with modules (reminder)

Controllers based on Humoto often have to receive commands/parameters from other software. Static configuration files are not always suitable for this purpose. We should decide if we want to add functionality to enable online/remote interaction with modules, and, if yes, how exactly it must be implemented.

I've already sent a brief review of possible options in the mailing list, it can be a starting point.

Continuous Integration Service

We have recently experienced a problem with CI service provided by INRIA: our virtual machines with their configurations were lost.

It is therefore important to consider a possibility of using of other free CI services. The main obstacle for this is that we also have to test non-public code and we don't want it to leak. If we decide to use some external CI service for public code only, the maintenance costs increase.

In any case we must find a way to backup configurations of the virtual machines.

alternative log file formats

The log file format is parsable by Matlab/Octave. Consider alternative formats, e.g., python.

Rework FSM for walking

Remove limit on the number of steps.
Support online change of reference velocities.

Remove assumption on alignment of the feet

Remove assumption on alignment of the feet in the initial / final DS.

Better handling of constant tasks (A^T * A)

Result of 'A^T * A' can be reused if the task is not modified from one iteration ot another.