Commit 947095b2 authored by Guilhem Saurel's avatar Guilhem Saurel
Browse files

Merge tag 'v3.3.0'

Release of version 3.3.0.
parents ff0c2241 9bde6675
# Copyright 2010, Olivier Stasse, JRL, CNRS/AIST
#
# This file is part of dynamic-graph.
# dynamic-graph is free software: you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public License
# as published by the Free Software Foundation, either version 3 of
# the License, or (at your option) any later version.
#
# dynamic-graph 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 Lesser Public License for more details. You should have
# received a copy of the GNU Lesser General Public License along with
# dynamic-graph. If not, see <http://www.gnu.org/licenses/>.
CMAKE_MINIMUM_REQUIRED(VERSION 2.6)
......@@ -19,7 +6,6 @@ INCLUDE(cmake/base.cmake)
INCLUDE(cmake/boost.cmake)
INCLUDE(cmake/eigen.cmake)
INCLUDE(cmake/pthread.cmake)
INCLUDE(cmake/cpack.cmake)
SET(PROJECT_ORG stack-of-tasks)
SET(PROJECT_NAME dynamic-graph)
......@@ -42,9 +28,6 @@ GENERATE_CONFIGURATION_HEADER(
GENERATE_CONFIGURATION_HEADER(
${HEADER_DIR}
config-tracer-real-time.hh DG_TRACERREALTIME tracer_real_time_EXPORTS)
GENERATE_CONFIGURATION_HEADER(
${HEADER_DIR}
config-contiifstream.hh DG_CONTIIFSTREAM contiifstream_EXPORTS)
# FIXME: to be changed into lib/dynamic-graph
# to avoid name collision when installing dynamic-graph in /usr.
......@@ -69,4 +52,3 @@ ADD_SUBDIRECTORY(include/${PROJECT_NAME})
ADD_SUBDIRECTORY(tests)
SETUP_PROJECT_FINALIZE()
SETUP_PROJECT_CPACK()
Subproject commit a33ae51993e5bc22ae2e5cd5131f85bd2ee6c8d1
Subproject commit 1d9aeca25e970d2d967fd5be0fb93fe961db121b
......@@ -4,3 +4,6 @@ IMAGE_PATH = @CMAKE_SOURCE_DIR@/doc/pictures \
@CMAKE_SOURCE_DIR@/doc/figures
FILE_PATTERNS = *.cc *.cpp *.h *.hh *.hxx
TAGFILES = \
"@CMAKE_INSTALL_PREFIX@/share/doc/dynamic-graph-python.doxytag = @CMAKE_INSTALL_PREFIX@/share/doc/dynamic-graph-python"
\ No newline at end of file
/**
\page debug Debugging
They are several ways to perform debugging in dynamic-graph depending on your needs or situation:
- If you just need to collect informations from signals (like rosbag). You can use
an entity called Tracer inside the graph:\subpage tracerdoc
- programmatically in C++ with macros \subpage subp_dbg_trace
- programmatically inside the entity in C++ using member of the entities:
\subpage tracerrealtimedoc
**/
/**
\page subp_dbg_trace Debugging with macros and level
\section subp_dbg_trace_intro Introduction
The idea of this class and collection of MACROS is to specify
a level for a message, and record the message in a stream according to this level.
In addition there are mechanisms allowing that no time
is wasted in condition test. You can therefore let the debugging messages
inside the code without impact on performances.
\section subp_dbg_trace_set_on_macros Setting up dgDEBUG macros
To allow message display the entity must be compiled with the macro
\code
#define VP_DEBUG 1
\endcode
Commenting or removing this macro disable all the messages specified
by the following macros.
The level up to which the messages are accepted for display is
specified by:
\code
#define VP_DEBUG_MODE 50
\endcode
In the constructor of the entity, the file where all the messages
are written is specified by:
\code
dynamicgraph::dgDEBUGFLOW.openFile("/tmp/dynamic-graph-traces.txt");
\endcode
\section subp_dbg_trace_using_macros Using dgDEBUG macros
To print that the beginning of a method is being executed use the following macros:
\code
dgDEBUGIN(5);
\endcode
5 here specifies the minimum level that you be specified by VP_DEBUG_MODE for this message
to be displayed.
It will generate the following output:
\code
/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#46) :# In {
\endcode
The output displays the name of the source file, the name of the method,
the line where is the macro, and the message itself.
When going out of the method:
\code
dgDEBUGOUT(5);
\endcode
This generates the following output:
\code
/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#54) :# Out }
\endcode
A message inside the code is written through:
\code
dgDEBUG(5) << "Here is a test" << std::endl;
\endcode
This generates the following output:
\code
/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#52) :Here is a test
\endcode
\section subp_dbg_trace_wrk_exp Working example
A full working example is given here:
\include ../tests/debug-trace.cpp
*/
/**
\page subpage_entities Entities
\section section_entities Entities
\subsection entity_definition General definition
\image html entity.png
Despite the fact that it looks very similar to a ROS node or a CORBA/OpenRTM server, an entity is simply a C++ object.
The main idea is that this entity is providing mostly a data-driven functionnality working at very high rate (\f$ 200 Hz\f$ or \f$ 1 kHz \f$)
and should have a minimal computational time foot-print.
For this \subpage subp_signals (or ports to use a more classical terminology) are providing a time dependency between data.
To implement this, an output signal is linked with a method of the entity. The method calls input signals or use other means
to get the needed data.
It might be provided by the connection with remote computers through a middleware, or specific protocols,
but in general the external data is based upon the sensor values provided by a "Device" entity.
For this reason the signal evaluations are realized through the cascade of dependencies and start from the evaluation of an input
signal of a periodic node (in general the device). This is realized inside a \b real-time thread.
To add flexibility to a node, it is possible to add command with arguments to modify the internal behavior of the entity
or get information from the entity.
As a command is in general asynchronous and rare with respect to the data-flow scheme for the signals the command is in general
executed in a \b none-real-time thread.
\subsection entity_classes Entity class
Entities are implemented as C++ classes and compiled as dynamic libraries. They can be loaded and instancied dynamically.
It is therefore necessary to specify the location of their dynamical libraries.
However given the time it might take to load the library, it is not advised to do that during a control-law computation.
Entity instanciation also implies memory allocation which is also time consuming and thus not advised inside a real-time thread.
The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
check the install log or the CMakeLists.txt file to check the installation path).
\subsection entities List of entities in this package
Since most of the functionality in projects using the dynamic-graph framework
is exposed from entities, here is a short description of all the entities contained in
this package. Note that most entities are contained in a binary file that closely matches
the entities' names in the scripts; loading this file with the plugin loader will
enable creation of this entity through the factory.
\li \ref tracerdoc
\li \ref tracerrealtimedoc
\subsection specific_semantics Specific semantics with entities
It is possible to derive classes and apply specific semantic for the entities. In our case we are interested in specific control semantics:
\li Tasks (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00089.html">here</a>)
\li Features (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00030.html">here</a>)
\li Solver (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00078.html">here</a>)
*/
/**
\page subp_how_to_use Using this package
\section usecase How to use this package
\subsection use_programmatically General introduction
Objects, which are derived from Entities (base class dynamicgraph::Entity), can be
declared within the code and compiled to shared libraries (.so/.dll files).
These libraries can be loaded at run-time using the PluginLoader methods,
and at the same time register their class names to the Factory (see the
examples in the <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/sot-core/master/doxygen-html">sot-core documentation</a>
for advanced control examples).
The Factory can then create instances of these objects and subsequently
register them in the Pool, where they can be listed, accessed, and acted upon
(see PoolStorage documentation). Basic commands defined by entities include
signal connection graph file generation, help and name print, and signals.
This is usually done through a scripting language such as python (see
<a hef="https://github.com/stack-of-tasks/dynamic-graph-python">dynamic-graph-python</a>)
The singletons made available by including the corresponding headers in this
module are:
\li dynamicgraph::FactoryStorage
\li dynamicgraph::PoolStorage
For an example of a program creating entities in C++, see the unit test
test_pool.cpp (in your package source directory/tests).
\subsection Tutorial
A tutorial is available <a href="http://stack-of-tasks.github.io/dynamic-graph-tutorial/">here</a>
\section sec_htw_helpers Helpers
When writing entities you might use some macros which are very useful to write your class.
They are given also in the <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/sot-core/master/doxygen-html">sot-core</a> package as well.
*/
/**
\page subp_factory Factory
\section sec_factory Factory
The class \ref dynamicgraph::FactoryStorage is a singleton which register the entity classes and which is allowing the instancation of such classes.
*/
/**
\page p_graph Graph
In this package, the graph considered are directed graphs.
In dynamic-graph a graph is build with:
- computational nodes which are entities \subpage subpage_entities.
- directed edges which are created by connecting input and output signals \subpage subp_signals.
- managing the nodes is done through a factory \subpage subp_factory providing classes and a way to create instances from this list of classes.
- the instances of node are handled through a pool \subpage subp_pool
We strongly recommend to use a scripting language such as Python to
manage the graph.
See <c>dynamic-graph-python</c> for more information on binding dynamic-graph with Python.
It is possible to display the graph of entities \subpage writegraphdoc
*/
/**
\page subp_installation Installation
\section sec_inst_dep Dependencies
dynamic-graph depends on:
<ul>
<li> boost </li>
<li> eigen </li>
<li> cmake </li>
</ul>
\section sec_inst_get_src Getting the source
The sources are available through github at the following URL:
<a href="https://github.com/stack-of-tasks/dynamic-graph">https://github.com/stack-of-tasks/dynamic-graph</a>
To clone:
\code
git clone https://github.com/stack-of-tasks/dynamic-graph.git
\endcode
\section sec_inst_comp Compiling
\code
cd dynamic-graph
mkdir _build
cd _build
cmake .. -DCMAKE_BUILD_TYPE=RELEASE
make
\endcode
*/
/**
\page subp_concept_intro General introduction
\section intro_dynamicGraph Introduction
The dynamic-graph package is used to connect computation nodes, "entities"
together using a graph system, akin to what Simulink does. Entities are connected
through input and output signals.
With the building blocks this package provides, you can easily create a full computation graph
for a given problem. It is the basis for the stack of tasks operation.
\subsection controlgraph Exemple: Real-time control
<p>To give a more concrete example, the real-time control used by the Gepetto group for the humanoid robot HRP-2
is detailled.</p>
<p>
Real-time control system are usually driven by a cyclic computational node which
needs to send a control reference value to each motors of a robot. To compute this
control reference values, sensor values need to be provided.
In the Stack-Of-Tasks special entities called Device are used to
provide an abstract interface to the hardware.</p>
A scheme of the real-time control graph used for the humanoid robot HRP-2 is depicted in the following figure:
\image html Concept-Software-Fig.png
You can find an example of a real example of control graph at \ref writegraphdoc.
<p>The device therefore has a specific input which should contain the control vector.
This control vector is the result of a computation solving a control problem.
The entity in charge of solving this control problem is called "Solver" in the previous
figure.
In the SoT framework it is often cast as an optimization problem.
This optimization problem is build using a control "Task" (not to be confused with the
general word task). A control "Task" regulates the difference with a "Feature" computed
on the current robot state and a "Desired Feature". For instance when walking, the regulated
feature is the robot's Center-Of-Mass (CoM) position. The "Feature" is computed using a
library using the robot model and the sensor value. The entity making this computation is "Dyn".
A walking pattern generator using foot-steps position given in advance generates the desired
value for the CoM.
Note that the "Dyn" entity uses the sensor provided by the entity "Robot". </p>
<p>
From a pure computer science viewpoint we wish to avoid recomputing data such as articular Jacobians
when this is unnecessary. Therefore the data generated by an entity through signals may have two types of
dependencies: one dependency related to time and dependencies on other signals. Internally an entity
does not recompute the data if no new information is available, it is simply providing the same information
computed before. Please note that this package provides only the computational framework to realize
the data dependency and the entities. Solvers, libraries to compute mechanical quantities are provided
in different packages.
</p>
<p>
Finally in order to dynamically create a graph, it is possible \b on-line to load classes of entities and
create instances of entities.</p>
\subsection Functionnalities
\li Support for extensions and modules using dynamic link libraries
\li Template-based signal definition, independent
\li Type-safe connection of input and output signals
\li On-demand signal computation as well as a caching system for signal values allow fast
computation of signal values, which is a critical point for real-time systems\n
See \ref scriptingabout
*/
......@@ -6,190 +6,28 @@
*
* CNRS/AIST
*
* This file is part of dynamic-graph.
* dynamic-graph is free software: you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation, either version 3 of
* the License, or (at your option) any later version.
* dynamic-graph 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 Lesser General Public License for more details. You should
* have received a copy of the GNU Lesser General Public License along
* with dynamic-graph. If not, see <http://www.gnu.org/licenses/>.
*/
/**
\mainpage
The dynamic-graph aims at building computational graphs for real-time control.
It provides the basic software functionnalities.
A more detailed introduction is available at \subpage subp_concept_intro.
\section intro_dynamicGraph Introduction
The dynamic-graph package is used to connect computation nodes, "entities"
together using a graph system, akin to what Simulink does. Entities are connected
through input and output signals.
With the building blocks this package provides, you can easily create a full computation graph
for a given problem. It is the basis for the stack of tasks operation.
\subsection controlgraph Exemple: Real-time control
<p>To give a more concrete example, the real-time control used by the Gepetto group for the humanoid robot HRP-2
is detailled.</p>
<p>
Real-time control system are usually driven by a cyclic computational node which
needs to send a control reference value to each motors of a robot. To compute this
control reference values, sensor values need to be provided.
In the Stack-Of-Tasks special entities called Device are used to
provide an abstract interface to the hardware.</p>
A scheme of the real-time control graph used for the humanoid robot HRP-2 is depicted in the following figure:
\image html Concept-Software-Fig.png
<p>The device therefore has a specific input which should contain the control vector.
This control vector is the result of a computation solving a control problem.
The entity in charge of solving this control problem is called "Solver" in the previous
figure.
In the SoT framework it is often cast as an optimization problem.
This optimization problem is build using a control "Task" (not to be confused with the
general word task). A control "Task" regulates the difference with a "Feature" computed
on the current robot state and a "Desired Feature". For instance when walking, the regulated
feature is the robot's Center-Of-Mass (CoM) position. The "Feature" is computed using a
library using the robot model and the sensor value. The entity making this computation is "Dyn".
A walking pattern generator using foot-steps position given in advance generates the desired
value for the CoM.
Note that the "Dyn" entity uses the sensor provided by the entity "Robot". </p>
<p>
From a pure computer science viewpoint we wish to avoid recomputing data such as articular Jacobians
when this is unnecessary. Therefore the data generated by an entity through signals may have two types of
dependencies: one dependency related to time and dependencies on other signals. Internally an entity
does not recompute the data if no new information is available, it is simply providing the same information
computed before. Please note that this package provides only the computational framework to realize
the data dependency and the entities. Solvers, libraries to compute mechanical quantities are provided
in different packages.
</p>
<p>
Finally in order to dynamically create a graph, it is possible \b on-line to load classes of entities and
create instances of entities.</p>
\subsection Functionnalities
\li Support for extensions and modules using dynamic link libraries
\li Template-based signal definition, independent
\li Type-safe connection of input and output signals
\li On-demand signal computation as well as a caching system for signal values allow fast
computation of signal values, which is a critical point for real-time systems\n
See \ref scriptingabout
\section entity Computational Entity
\image html entity.png
\subsection entity_definition General definition
Despite the fact that it looks very similar to a ROS node or a CORBA/OpenRTM server, an entity is simply a C++ object.
The main idea is that this entity is providing mostly a data-driven functionnality working at very high rate (\f$ 200 Hz\f$ or \f$ 1 kHz \f$)
and should have a minimal computational time foot-print.
For this signals (or ports to use a more classical terminology) are providing a time dependency between data.
To implement this, an output signal is linked with a method of the entity. The method calls input signals or use other means
to get the needed data.
It might be provided by the connection with remote computers through a middleware, or specific protocols,
but in general the external data is based upon the sensor values provided by a "Device" entity.
For this reason the signal evaluations are realized through the cascade of dependencies and start from the evaluation of an input
signal of a periodic node (in general the device). This is realized inside a \b real-time thread.
To add flexibility to a node, it is possible to add command with arguments to modify the internal behavior of the entity
or get information from the entity.
As a command is in general asynchronous and rare with respect to the data-flow scheme for the signals the command is in general
executed in a \b none-real-time thread.
\subsection entity_classes Entity class
Entities are implemented as C++ classes and compiled as dynamic libraries. They can be loaded and instancied dynamically.
It is therefore necessary to specify the location of their dynamical libraries.
However given the time it might take to load the library, it is not advised to do that during a control-law computation.
Entity instanciation also implies memory allocation which is also time consuming and thus not advised inside a real-time thread.
The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
check the install log or the CMakeLists.txt file to check the installation path).
\subsection entities List of entities in this package
Since most of the functionality in projects using the dynamic-graph framework
is exposed from entities, here is a short description of all the entities contained in
this package. Note that most entities are contained in a binary file that closely matches
the entities' names in the scripts; loading this file with the plugin loader will
enable creation of this entity through the factory.
\li \ref tracerdoc
\li \ref tracerrealtimedoc
\subsection specific_semantics Specific semantics with entities
It is possible to derive classes and apply specific semantic for the entities. In our case we are interested in specific control semantics:
\li Tasks (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00089.html">here</a>)
\li Features (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00030.html">here</a>)
\li Solver (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00078.html">here</a>)
\section sigintro Signals
Entities can output different types of signals. All signals are templated by a Time
tick type parameter (which is used in the caching of signals) - usually \c int. Signals
are also templated after the type of data they accept or provide. For example:
(example)
For a more detailed programmer-oriented description of signals, please see \ref signals
\section graph Graph
In this package, the graph considered are directed graphs.
\subsection factory Factory
The class \ref dynamicgraph::FactoryStorage is a singleton which register the entity classes and which is allowing the instancation of such classes.
\subsection pool Pool
The class \ref dynamicgraph::PoolStorage keeps track of the entities instanciated with the factory.
The entities are the graph nodes. Signals are constructed during the class instanciation, they do not live independently
from the entities. Signals are the directed edges of the graph.
The pool can write a file representing the graph of entities.
\section usecase How to use this package
\subsection use_programmtically Programmatically
Objects, which are derived from Entities (base class dynamicgraph::Entity), can be
declared within the code and compiled to shared libraries (.so/.dll files).
These libraries can be loaded at run-time using the PluginLoader methods,
and at the same time register their class names to the Factory (see the
examples in the SOT documentation to learn how).
The Factory can then create instances of these objects and subsequently
register them in the Pool, where they can be listed, accessed, and acted upon
(see PoolStorage documentation). Basic commands defined by entities include
signal connection graph file generation, help and name print, and signals.
The singletons made available by including the corresponding headers in this
module are:
\li dynamicgraph::FactoryStorage
\li dynamicgraph::PoolStorage
For an example of a program creating entities in C++, see the unit test
test_pool.cpp (in your package source directory/unitTesting).
\subsection Tutorial
A tutorial is available <a href="http://stack-of-tasks.github.io/dynamic-graph-tutorial/">here</a>
\section references References
\anchor Mansard2009
<b> "A versatile Generalized Inverted Kinematics implementation for collaborative working humanoid robots: The Stack Of Tasks"</b>,
<em>N. Mansard, O. Stasse, P. Evrard, A. Kheddar,</em>
Int. Conf. on Autonomous Robots, ICAR, 2009
\anchor Mansard2007
<b>"Task sequencing for sensor-based control"</b>,
<em>N. Mansard, F. Chaumette,</em>
IEEE Trans. on Robotics, 23(1):60-72, February 2007
The installation instruction are given at \subpage subp_installation.
The software graph structure is detailled in \subpage p_graph
For debugging your entities detailed instructions are given in \subpage debug
For citing the software in your research work please refer to \subpage subp_references
\namespace dynamicgraph This is the namespace where every object and class of this library is located.
\defgroup debug Debugging
\defgroup dgraph Core classes and objects
@{
......
/**
\page subp_pool Pool
\section pool Pool
The class \ref dynamicgraph::PoolStorage keeps track of the entities instanciated with the factory.
The entities are the graph nodes. Signals are constructed during the class instanciation, they do not live independently
from the entities. Signals are the directed edges of the graph.
The pool can write a file representing the graph of entities.
*/
/**
\page subp_references References
\section sec_refer References
Please when referencing the Stack-Of-Tasks use the following reference:
\anchor Mansard2009
<b> <a href="https://hal-lirmm.ccsd.cnrs.fr/lirmm-00796736/document">
"A versatile Generalized Inverted Kinematics implementation for collaborative working humanoid robots: The Stack Of Tasks"</a>
</b>,
<em>N. Mansard, O. Stasse, P. Evrard, A. Kheddar,</em>
Int. Conf. on Autonomous Robots, ICAR, 2009
\anchor Mansard2007
<b>"Task sequencing for sensor-based control"</b>,
<em>N. Mansard, F. Chaumette,</em>
IEEE Trans. on Robotics, 23(1):60-72, February 2007
*/
/**
\page subp_signals Signals
\section sec_sigintro Signals
Entities can output different types of signals. To guarante real-time perforamces, signals are implemented
using C++ and mecanism which have a low time foot-print.
All signals are templated by a Time
tick type parameter (which is used in the caching of signals) - usually \c int. Signals
are also templated after the type of data they accept or provide. For example:
(example)
For a more detailed programmer-oriented description of signals, please see \ref signals
*/
/**
\page tracerrealtimedoc TracerRealTime
\section description Description
\section tracerrealtimedoc_description Description
The \b TracerRealTime entity monitors a set of signals with real-time constraints; its
function is very similar to the Tracer, except that all traces are recorded to a
memory buffer, which can be emptied at any time.
\section commands Commands
\section tracerrealtimedoc_commands Commands
The \b commands that this entity exposes are:
\code
empty (discards all buffers)
......@@ -16,13 +18,12 @@ Plus all the commands exposed by \ref tracerdoc
For more information on the signals exposed by this entity, please check the
code documentation of the dynamicgraph::Tracer class.
\section sample Sample usage
\section tracerrealtimedoc_sample Sample usage
See \ref tracerdoc for a code sample of using TracerRealTime.
\section addi Additional information
\section tracerrealtimedoc_addi Additional information
See doxygen documentation for the class dynamicgraph::TracerRealTime
\section generates Generated plugin file