package.h

/*
 * Copyright 2010,
 * François Bleibel,
 * Thomas Moulard,
 * Olivier Stasse,
 *
 * 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



\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




\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

\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
@{

Classes, entities and binaries that make up the core of the dynamic-graph library are listed here.
@}

\defgroup signals Signals
@{
This part provides the mechanism to transfer information
from one entity to another. There are three main types of signals,
all deriving from the common class dynamicgraph::SignalBase :
\li dynamicgraph::Signal : a "normal" signal, passing data around \b by \b value
\li dynamicgraph::SignalPtr : a signal used for efficient passing of large data, by reference (or rather, C pointers)*
\li dynamicgraph::SignalTimeDependent : a signal that enforces a time dependency between other signals,
making sure its inputs are up to date on access, using a incrementing time tick as reference.

\n* Note: this may cause a problem if this package is used in a multithreaded program.

Signals can be grouped together using dynamicgraph::SignalArray.

Signals implement a caching mechanism by storing the last computation time tick.

For more information, please see the individual signal pages.

\b Samples

\li The following code ensures the jacobian output signal uses up-to-date values for its
computations, when accessed.

\code
  // This signal returns the Jacobian of the current value
  //  according to the robot state
  dg::SignalTimeDependent<ml::Matrix,int> jacobianSOUT;

  (...)

  jacobianSOUT.addDependency( positionSIN );
  jacobianSOUT.addDependency( articularJacobianSIN );

\endcode

@}

*/