Improve documentation (#28)

README.md

@@ -1,7 +1,7 @@
 ### <img src="https://i.imgur.com/ZOfGZwB.png" height="60" />
 
 [![Build Status](http://build.ros.org/buildStatus/icon?job=Kdev__ifopt__ubuntu_xenial_amd64)](http://build.ros.org/view/Kdev/job/Kdev__ifopt__ubuntu_xenial_amd64/)
-[![Documentation](https://img.shields.io/badge/docs-generated-brightgreen.svg)](http://docs.ros.org/kinetic/api/ifopt/html/)
+[![Documentation](https://img.shields.io/badge/docs-generated-brightgreen.svg)](http://docs.ros.org/api/ifopt/html/)
 [![ROS integration](https://img.shields.io/badge/ROS-integration-blue.svg)](http://wiki.ros.org/ifopt)
 ![](https://tokei.rs/b1/github/ethz-adrl/ifopt)
 [![CodeFactor](https://www.codefactor.io/repository/github/ethz-adrl/ifopt/badge)](https://www.codefactor.io/repository/github/ethz-adrl/ifopt)
@@ -18,41 +18,47 @@ An example nonlinear optimization problem to solve is defined as:
 
 * To see how this problem is formulated, see [*test_vars_constr_cost.h*](ifopt_core/test/ifopt/test_vars_constr_cost.h).   
 * Afterwards the problem can be solved using e.g. Ipopt as shown in [*ex_test_ipopt.cc*](ifopt_ipopt/test/ex_test_ipopt.cc).
-* Further example: [towr] - multiple variable- and constraint [sets](https://i.imgur.com/4yhohZF.png) to generate motions for legged robots.
 
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#install">Install</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#develop">Develop</a> •
+  <a href="#contribute">Contribute</a> •
+  <a href="#publications">Publications</a> •
+  <a href="#authors">Authors</a>
+</p>
 
 ## Features
 *Combines* the advantages of [Ipopt] / [Snopt] and [Eigen]:
 
-| [Ipopt] / [Snopt] | + | [Eigen]  |
-|----------|--------|----| 
-|:heavy_check_mark: high-quality solvers for nonlinear optimization  |  | :heavy_check_mark: modern, intuitive formulations of vectors and matrices |
-|:x: C++ API inconvenient and error-prone (raw pointers, index management, jacobian construction) | | :heavy_check_mark: highly efficient implementations |       
-|:x: linking and exporting difficult  | | |
-
-* Solver independent formulation of variables and constraints with Eigen      
-* Automatic index management by formulating similar variables (or constraints) as independent sets   
-* Highly efficient due to Eigen sparse matrix formulations  
-* cmake scripts to easily `find_package(ifopt)` in your project    
-* [catkin] / [ROS] integration (optional)       
+[Ipopt] / [Snopt]  | [Eigen] 
+----------|---------
+:heavy_check_mark: high-quality solvers for nonlinear optimization  | :heavy_check_mark: modern, intuitive formulations of vectors and matrices 
+:x: C++ API inconvenient and error-prone (raw pointers, index management, jacobian construction) | :heavy_check_mark: highly efficient implementations   
+:x: linking and exporting difficult  | 
+
+* Solver independent formulation of variables and constraints with Eigen (highly efficient)     
+* Automatic index management by formulation of [variable- and constraint-sets](http://docs.ros.org/api/ifopt/html/group__ProblemFormulation.html)  
+* Integration: pure cmake `find_package(ifopt)` or [catkin]/[ROS] (optional)       
 * light-weight (~[2k lines of code](https://i.imgur.com/NCPJsSw.png)) makes it easy to use and extend    
 
 
 ## Install
-The easiest way to install is through the [ROS binaries](http://wiki.ros.org/ifopt):
+The easiest way to install is through the [ROS binaries](http://wiki.ros.org/ifopt) and you're all set!
 ```
 sudo apt-get install ros-<distro>-ifopt
 ```
 
-## Build from source
+#### Install dependencies
 In case you don't use ROS or the binaries don't exist for your distro, you can easily build these
 packages from source. For this, install the required dependencies [Cmake], [Eigen] and [Ipopt] using
 ```
 sudo apt-get install cmake libeigen3-dev coinor-libipopt-dev
 ```
-If you want to link to a local installation of [Ipopt] or to [Snopt], see the [doxygen documentation](http://docs.ros.org/kinetic/api/ifopt/html/).
+If you want to link to a local installation of [Ipopt] or to [Snopt], see [here](#additional-information).
 
-#### Building with cmake
+#### Build with cmake
 * Install
   ```bash
   git clone https://github.com/ethz-adrl/ifopt.git && cd ifopt
@@ -72,7 +78,7 @@ If you want to link to a local installation of [Ipopt] or to [Snopt], see the [d
   target_link_libraries(main PUBLIC ifopt::ifopt_ipopt) 
   ```
         
-#### Building with catkin
+#### Build with catkin
 * Install: Download [catkin] or [catkin command line tools], then:
   ```bash
   cd catkin_ws/src
@@ -95,7 +101,8 @@ If you want to link to a local installation of [Ipopt] or to [Snopt], see the [d
   </package>
   ```
 
-## Test 
+## Examples 
+#### Unit tests & toy problem
 Navigate to your build folder in which the `Makefile` resides, which depends
 on how you built the code:
 ```bash
@@ -120,22 +127,20 @@ Output:
 1.0 0.0
 ```
 
-Each set of variables, costs and constraints are formulated by one C++ object
-purely through Eigen vectors and matrices and independent from any specific solver.
-Although the above [example](ifopt_core/test/ifopt/test_vars_constr_cost.h) adds just one, 
-multiple sets of variables or constraints can be added to the NLP and ifopt manages 
-the overall variable vector and jacobian, so each set can be implemented independent of 
-the others. A more involved problem definition with multiple sets 
-of variables and constraints, taken from [towr] can be seen in the following: 
+#### towr
+A more involved problem, taken from [towr], with multiple sets of variables and constraints to generate motions for legged robots produces the following: 
 
 <img align="center" height="500" src="https://i.imgur.com/4yhohZF.png"/>
 
-## Authors 
-[Alexander W. Winkler](https://awinkler.github.io/) - Initial Work/Maintainer
+## Develop
+Useful information for developers is given in the doxygen documentation:
 
-This was has been carried out at the following institutions:
+ * For an overview of how to formulate your problem, start [ProblemFormulation](http://docs.ros.org/api/ifopt/html/group__ProblemFormulation.html).
+ * A nice graphical overview as UML can be seen [here](http://docs.ros.org/api/ifopt/html/inherits.html).
 
-[<img src="https://i.imgur.com/aGOnNTZ.png" height="45" />](https://www.ethz.ch/en.html "ETH Zurich") &nbsp; &nbsp; &nbsp; &nbsp; [<img src="https://i.imgur.com/uCvLs2j.png" height="45" />](http://www.adrl.ethz.ch/doku.php "Agile and Dexterous Robotics Lab")  &nbsp; &nbsp; &nbsp; &nbsp;[<img src="https://i.imgur.com/gYxWH9p.png" height="45" />](http://www.rsl.ethz.ch/ "Robotic Systems Lab")
+## Contribute
+We love pull request, whether its interfaces to additional solvers, bug fixes, unit tests or updating the documentation. Please have a look at [CONTRIBUTING.md](CONTRIBUTING.md) for more information. 
+See here the list of [contributors](https://github.com/ethz-adrl/ifopt/graphs/contributors) who participated in this project.
 
 
 ## Publications
@@ -153,16 +158,50 @@ If you use this work, please consider citing as follows:
 The research project within which this code was developed:
 * A. W. Winkler, D. Bellicoso, M. Hutter, J. Buchli, [Gait and Trajectory Optimization for Legged Systems through Phase-based End-Effector Parameterization](http://awinkler.me), IEEE Robotics and Automation Letters (RA-L), 2018:
 
-## Contributing
-We love pull request, whether its interfaces to additional solvers, bug fixes, unit tests or updating the documentation. Please have a look at [CONTRIBUTING.md](CONTRIBUTING.md) for more information. 
-See here the list of [contributors](https://github.com/ethz-adrl/ifopt/graphs/contributors) who participated in this project.
 
+## Authors 
+[Alexander W. Winkler](https://awinkler.github.io/) - Initial Work/Maintainer
 
-##  Bugs & Feature Requests
-To report bugs, request features or ask questions, please have a look at [CONTRIBUTING.md](CONTRIBUTING.md). 
+This was has been carried out at the following institutions:
+
+[<img src="https://i.imgur.com/aGOnNTZ.png" height="45" />](https://www.ethz.ch/en.html "ETH Zurich") &nbsp; &nbsp; &nbsp; &nbsp; [<img src="https://i.imgur.com/uCvLs2j.png" height="45" />](http://www.adrl.ethz.ch/doku.php "Agile and Dexterous Robotics Lab")  &nbsp; &nbsp; &nbsp; &nbsp;[<img src="https://i.imgur.com/gYxWH9p.png" height="45" />](http://www.rsl.ethz.ch/ "Robotic Systems Lab")
 
 
 
+## Additional Information
+#### Linking to custom Ipopt or Snopt
+If you are building from source and want to use a locally installed version of [Ipopt] add the path to your
+Ipopt build folder to your `~/.bashrc`, e.g.
+```bash
+export IPOPT_DIR=/home/your_name/Code/Ipopt-3.12.8/build
+```
+
+In case your OS doesn't provide the precompiled binaries or the required version,
+you can also easily install Ipopt from source as described [here](https://www.coin-or.org/Ipopt/documentation/node14.html). This summary might work for you:
+```bash
+wget https://www.coin-or.org/download/source/Ipopt/Ipopt-3.11.10.zip
+unzip Ipopt-3.11.10.zip
+cd Ipopt-3.11.10/ThirdParty/Mumps
+./get.Mumps  # HSL routines are faster (http://www.hsl.rl.ac.uk/ipopt/)
+cd ../../
+mkdir build && cd build
+../configure --prefix=/usr/local
+make
+make test
+make install
+export IPOPT_DIR=`pwd`
+```
+
+If you need an interface to [Snopt], point cmake to that build folder in your `~/.bashrc` through e.g.
+```bash
+export SNOPT_DIR=/home/your_name/Code/Snopt
+```
+and run cmake as 
+```bash
+cmake -DBUILD_SNOPT=ON ..
+```
+
+
 [CMake]: https://cmake.org/cmake/help/v3.0/
 [Eigen]: http://eigen.tuxfamily.org
 [Ipopt]: https://projects.coin-or.org/Ipopt

doc/mainpage.md

@@ -1,96 +1,12 @@
 IFOPT - Interface for Nonlinear Optimizers {#mainpage}
----------------------
+=================
 
-*A modern, light-weight, [Eigen]-based C++ interface to Nonlinear Programming solvers, such as [Ipopt] and [Snopt].* 
+*A modern, light-weight, Eigen-based C++ interface to Nonlinear Programming solvers, such as %Ipopt and Snopt to solve problem like this:* 
 
-|Solves a Nonlinear Optimization Problem as: | |
-| -------|------ |
-| \image html example_nlp.png | |
+\image html example_nlp.png
 
-* **To see how this problem is formulated, see test_vars_constr_cost.h.** 
-* **Afterwards the problem can be solved using e.g. IPOPT as shown in ex_test_ipopt.cc**.
-
-Features:
-* Related variables and constraints are implemented (grouped) in *independent sets*. Ifopt automatically generates the overall problem from these sets. No more changing indices in your variable vector or Jacobian when adding or removing variables/constraints. See this large [problem](https://i.imgur.com/4yhohZF.png), that requires multiple variable- and constraint sets to generate the motion for legged robot (implemented in [towr]).
-* [Eigen] allows inuitive formulation and fast performance due to sparse matrix exploitation.  
-* exports cmake scripts to easily `find_package(ifopt)` in your project.  
-* [catkin] integration (optional).  
-* light-weight (~[2k lines of code](https://i.imgur.com/NCPJsSw.png)) makes it easy to use and extend.  
-
-
-[TOC]
-
-Install {#install}
-========================
-In case the binaries for you ROS distro don't exist, for pure [CMake] build
-as well as all required dependencies, please see
-github 
+For an overview, see
 <a href="https://github.com/ethz-adrl/ifopt/blob/master/README.md">
-README.md
+Github's README.md
 </a>.
 
-In all other cases, this should work for you:
-\code{.sh}
-sudo apt-get install ros-<ros-distro>-ifopt
-\endcode
-
-Linking to custom Ipopt or Snopt {#link}
----------------------------
-If you are building from source and want to use a locally installed version of [Ipopt] add the path to your
-Ipopt build folder to your `~/.bashrc`, e.g.
-\code{.sh}
-export IPOPT_DIR=/home/your_name/Code/Ipopt-3.12.8/build
-\endcode
-
-In case your OS doesn't provide the precompiled binaries or the required version,
-you can also easily install Ipopt from source as described [here](https://www.coin-or.org/Ipopt/documentation/node14.html). This summary might work for you:
-\code{.sh}
-wget https://www.coin-or.org/download/source/Ipopt/Ipopt-3.11.10.zip
-unzip Ipopt-3.11.10.zip
-cd Ipopt-3.11.10/ThirdParty/Mumps
-./get.Mumps  # HSL routines are faster (http://www.hsl.rl.ac.uk/ipopt/)
-cd ../../
-mkdir build && cd build
-../configure --prefix=/usr/local
-make
-make test
-make install
-export IPOPT_DIR=`pwd`
-\endcode
-
-If you need an interface to [Snopt], point cmake to that build folder in your `~/.bashrc` through e.g.
-\code{.sh}
-export SNOPT_DIR=/home/your_name/Code/Snopt
-\endcode
-and run cmake as 
-\code{.sh}
-cmake -DBUILD_SNOPT=ON ..
-\endcode
-
-
-Contribute {#contribute}
-==========================
-We love pull requests. Please see 
-<a href="https://github.com/ethz-adrl/ifopt/blob/master/CONTRIBUTING.md">
-CONTRIBUTING.md
-</a> if you want to contribute.
-See here the list of 
-[contributors](https://github.com/ethz-adrl/ifopt/graphs/contributors) 
-who participated in this project.
-
-
-Authors {#authors}
-=======================
-[Alexander W. Winkler](http://awinkler.me) - Initial Developer & Maintenance
-
-
-[ROS]: http://www.ros.org
-[xpp]: http://wiki.ros.org/xpp
-[catkin]: http://wiki.ros.org/catkin
-[Eigen]: http://eigen.tuxfamily.org
-[CMake]: https://cmake.org/cmake/help/v3.0/
-[Ipopt]: https://projects.coin-or.org/Ipopt
-[Snopt]: http://ampl.com/products/solvers/solvers-we-sell/snopt/
-[towr]: https://github.com/ethz-adrl/towr
-
-

doc/manifest.yaml

@@ -1,7 +1,7 @@
 actions: []
 authors: Alexander W. Winkler
 brief: ''
-bugtracker: ''
+bugtracker: http://github.com/ethz-adrl/ifopt/issues
 depends:
 - coinor-libipopt-dev
 - cmake
@@ -13,7 +13,7 @@ description: "An <a href=\"http://eigen.tuxfamily.org\">Eigen-</a>\n    based in
   \ and \n    constraints using Eigen. Easy integration in your projects in catkin\n\
   \    or pure cmake."
 license: BSD
-maintainers: Alexander W. Winkler <winklera@ethz.ch>
+maintainers: Alexander W. Winkler <alexander.w.winkler@gmail.com>
 msgs: []
 package_type: package
 repo_url: ''

ifopt_core/include/ifopt/bounds.h

@@ -38,8 +38,6 @@ namespace ifopt {
 struct Bounds {
   /**
    * @brief Creates a bound between @a lower and @a upper.
-   *
-   * @ingroup ProblemFormulation
    */
   Bounds(double lower = 0.0, double upper = 0.0)
   {

ifopt_core/include/ifopt/composite.h

@@ -50,23 +50,15 @@ namespace ifopt {
 /**
  * @brief Interface representing either Variable, Cost or Constraint.
  *
- * This structure allows a user to define individual and independent variable
- * sets, constraints and costs without having to worry about how to organize
- * them with respect to each other.
- *
- * The high-level idea is that variables, costs and constraints can all be fit
- * into the same interface (Component). For example, each has a "value", which
- * is either the actual value of the variables, the constraint value g or the
- * cost. Additionally, a real-world optimization problem usually doesn't just
- * contain one set of variables, but is comprised of @a multiple variable sets,
- * constraints and cost terms (Composite). This representation provides one
- * common interface ("smallest common denominator") that can be contain either
- * individual variables/costs/constraints or a Composite of these. This pattern
+ * Variables, costs and constraints can all be fit into the same interface
+ * (Component). For example, each has a "value", which is either the actual
+ * value of the variables, the constraint value g or the cost.
+ * This representation provides one common interface
+ * ("smallest common denominator") that can be contain either individual
+ * variables/costs/constraints or a Composite of these. This pattern
  * takes care of stacking variables, ordering Jacobians and providing bounds
- * for the complete problem without duplicating code.
- *
- * For more information on the composite pattern visit
- * https://sourcemaking.com/design_patterns/composite
+ * for the complete problem without duplicating code. For more information on
+ * the composite pattern visit https://sourcemaking.com/design_patterns/composite
  */
 class Component {
 public:
@@ -137,8 +129,9 @@ class Component {
   /**
    * @brief Prints the relevant information (name, rows, values) of this component.
    * @param tolerance  When to flag constraint/bound violation.
+   * @param index_start  Of this specific variables-, constraint- or cost set.
    */
-  virtual void Print(double tolerance) const;
+  virtual void Print(double tolerance, int& index_start) const;
 
   /**
    * @brief Sets the number of rows of this component.
@@ -187,7 +180,7 @@ class Composite : public Component {
   Jacobian GetJacobian () const override;
   VecBound GetBounds   () const override;
   void SetVariables(const VectorXd& x) override;
-  void Print(double tolerance) const override;
+  void PrintAll() const;
 
   /**
    * @brief  Access generic component with the specified name.

ifopt_core/include/ifopt/constraint_set.h

@@ -42,6 +42,9 @@ namespace ifopt {
  * @c n rows is given by:
  * lower_bound < g(x) < upper_bound
  *
+ * These constraint sets are later then stitched together to form the overall
+ * problem.
+ *
  * @ingroup ProblemFormulation
  * @sa Component
  */

ifopt_core/include/ifopt/cost_term.h

@@ -64,10 +64,13 @@ class CostTerm : public ConstraintSet {
    * @brief  Returns infinite bounds (e.g. no bounds).
    */
   VecBound GetBounds() const final;
+
+  /**
+   * Cost term printout slightly different from variables/constraints.
+   */
+  void Print (double tol, int& index) const final;
 };
 
 }
 
-
-
 #endif /* IFOPT_INCLUDE_IFOPT_COST_TERM_H_ */