/*!

\page install_guide Installation

@tableofcontents

\section req Requirements:

\subsection req-system System Requirements
- Ubuntu 16.04 or 18.04
- a compiler with C++14 support, e.g. gcc or clang


\subsection req-dependencies Required Dependencies
 - install <a href="http://eigen.tuxfamily.org/index.php?title=Main_Page">Eigen 3</a> via
  \code{.sh}
  sudo apt-get update
  sudo apt-get install libeigen3-dev
  \endcode
 - install boost
 \code{.sh}
 sudo apt-get install libboost-all-dev
 \endcode
 - clone the <a href="https://github.com/ethz-asl/kindr">kindr</a> library into your workspace
  \code{.sh}
  cd ~/your_workspace/src
  git clone https://github.com/ANYbotics/kindr.git
  \endcode
 - finally, clone the control toolbox into your workspace
  \code{.sh}
  cd ~/your_workspace/src
  git clone https://github.com/ethz-adrl/control-toolbox.git
  \endcode

\section build Building the CT
\subsection build-ros For ROS or catkin users
\subsubsection build-ros-main Compiling the Library
It is assumed that you have a valid catkin-workspace set up, e.g. using <a href="https://catkin-tools.readthedocs.io/en/latest/">catkin tools</a>.
Then, execute the following steps.
\code{.sh}
cd ~/your_workspace
catkin build -DCMAKE_BUILD_TYPE=Release
\endcode

\subsubsection build-ros-examples Building and running examples
To build an run the examples, e.g. the optimal control and optimal filtering examples:
\code{.sh}
cd ~/your_workspace
catkin build -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=true
source devel/setup.bash
rosrun ct_optcon ex_NLOC
rosrun ct_optcon ex_KalmanFiltering
\endcode

\subsubsection build-ros-tests Building and running the unit tests
To build an run the unit tests:
\code{.sh}
cd ~/your_workspace
catkin build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=true
source /devel/setup.bash
roscd ct_core && catkin build -v --this --no-deps --make-args run_tests
roscd ct_optcon && catkin build -v --this --no-deps --make-args run_tests
roscd ct_rbd && catkin build -v --this --no-deps --make-args run_tests
roscd ct_models && catkin build -v --this --no-deps --make-args run_tests
\endcode

\subsubsection build-ros-doc Building the documentation
To build the documentation execute
\code{.sh}
catkin build ct_doc -v --make-args doc
\endcode
This will build the documentation. The index.html can be found in ct_doc/doc/html



\subsection build-cmake Using plain cmake.
\subsubsection build-cmake-main Compiling the Library
First, make sure you build and install the kindr-library, see <a href="https://github.com/ANYbotics/kindr#building">here</a>.
Then go to your local clone of the control toolbox and run the build script:
\code{.sh}
cd your_workspace/control-toolbox/ct
chmod 775 build_ct.sh
./build_ct.sh -DCMAKE_BUILD_TYPE=Release
\endcode

\subsubsection build-cmake-examples Building and running examples
Then go to your local clone of the control toolbox and run the build script with the following flags.
\code{.sh}
cd your_workspace/control-toolbox/ct
./build_ct.sh -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=true
\endcode
This creates a /build subdirectory in every single CT-project, where the examples will be located.
For running the nonlinear optimal control or filtering examples, for instance, go to your workspace an run
\code{.sh}
./src/control-toolbox/ct_optcon/build/examples/ex_NLOC
./src/control-toolbox/ct_optcon/build/examples/ex_KalmanFiltering
\endcode

\subsubsection build-cmake-tests Building and running the unit tests
To build an run the unit tests, you can either call the target 'run_tests' manually via "make run_tests", or use the convenience script
\code{.sh}
cd your_workspace/control-toolbox/ct
./run_unit_tests.sh
\endcode

\subsubsection build-cmake-doc Building the documentation
\code{.sh}
cd your_workspace/control-toolbox/ct
chmod 775 build_doc.sh
./build_doc.sh
\endcode
The index.html can be found in ct_doc/doc/html

\subsubsection build-cmake-cleanup Clean up
In order to clean up the build workspaces, run the clean script
\code{.sh}
cd your_workspace/control-toolbox/ct
chmod 775 clean_ct.sh
./clean_ct.sh
\endcode


\section opt_dep Optional Dependencies and Bindings
The following dependencies and bindings are optional but can help to enhance the user-experience or performance of the CT

 - <a href="http://www.netlib.org/lapack/">lapack</a> (enables Schur method as an alternative to iterative method in ct::optcon::LQR)
 \code{.sh} $ sudo apt-get install liblapack-dev \endcode

 - <a href="https://clang.llvm.org/">clang</a> compiler (faster compilation for large linear models), install from command-line via
 \code{.sh} $ sudo apt-get install clang \endcode
 and possibly replace `clang` with a more specific version, e.g. `clang-3.8`.
 Please make sure that the `clang` and `clang++` commands are in your path.
 You may need to create a symbolic link in `/usr/bin` or use a bash alias.

 - <a href="https://projects.coin-or.org/Ipopt">IPOPT</a> or <a href="http://www.sbsi-sol-optimize.com/asp/sol_product_snopt.htm">SNOPT</a>
  (for ct::optcon::SnoptSolver and ct::optcon::IpoptSolver as used by ct::optcon::DMS)

 - <a href="https://github.com/giaf/blasfeo">blasfeo</a> linear algebra and <a href="https://github.com/giaf/hpipm">HPIPM solver</a> as
 alternative high-performance (constrained) linear-quadratic optimal control solver. The CT currently supports a hpipm version close to master. 
 Please use the script install_hpipm.sh in control-toolbox/ct in order to retrieve a version of hpipm which is guaranteed to be tested
 in combination with CT. Detailed reference about blasefeo can be found <a href="https://arxiv.org/abs/1704.02457">here</a>.
 Both packages were developed by <a href="https://www.syscop.de/people/dr-gianluca-frison">Gianluca Frison</a>, <a href="https://www.syscop.de/">University of Freiburg</a>.
 Warning note : When installing blasfeo, a configuration step may be necessary. See https://blasfeo.syscop.de/docs/install/#configuration for how to set the build target to your architecture.
 We advice to run the tests provided by blasfeo to check the correct installation. If not configured properly, blasfeo may be installed succesfully, the CT may be built succesfully with hpipm dependencies, but a "illegal operation (core dumped)" is raised when calling hpipm.

 - install the <a href="http://catkin-tools.readthedocs.io/en/latest/verbs/catkin_build.html">catkin_tools</a> build system
 \code{.sh}
 sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu `lsb_release -sc` main" > /etc/apt/sources.list.d/ros-latest.list'
 wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
 sudo apt-get update
 sudo apt-get install python-catkin-tools
 \endcode

 - <a href="http://qwt.sourceforge.net/">Qwt</a> (for basic plotting)

 - MATLAB (for Matlab logging)

 - <a href="https://clang.llvm.org/docs/ClangFormat.html">clang-format</a>, install via
  \code{.sh}
 $ sudo apt-get install clang-format
 \endcode

\section linux_packages Linux Packages

\subsection arch_linux Arch Linux
Note: Installing Control Toolbox on Arch Linux is not tested by the developers.

Control Toolbox is available in the Arch User Repository
(<a href="https://wiki.archlinux.org/index.php/Arch_User_Repository">AUR</a>) as
<a href="https://aur.archlinux.org/packages/control-toolbox/">control-toolbox</a>.
Note you can manually install the package by following the instructions on the
<a href="https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages">Arch Wiki</a>
or use an <a href="https://wiki.archlinux.org/index.php/AUR_helpers">AUR helper</a>
like <a href="https://aur.archlinux.org/packages/yay/">yay</a> (recommended for
ease of install).

\subsubsection install_opt_dep Install Optional Dependencies
 \code{.sh}
 yay -S lapack clang cppad cppadcodegen coin-or-ipopt hpipm qwt matlab clang-format
 \endcode

\subsubsection install_ct Install Control Toolbox
 \code{.sh}
 yay -S control-toolbox
 \endcode

To discuss any issues related to this package refer to the comments section on
the AUR page of control-toolbox
<a href="https://aur.archlinux.org/packages/control-toolbox">here</a>.



\section additional_arguments Additional build arguments
The following additional build flags are available, which can be appended to the build command above

Build Flag  | Default value | Description
------------- | ------------- | ------------
-DBUILD_EXAMPLES=\<BOOL> | FALSE  | Builds examples for all packages
-DBUILD_HYQ_FULL=\<FALSE> | FALSE | Build HyQ examples and executables (warning: slow with GCC!)
-DUSE_CLANG=\<BOOL> | FALSE  | Use CLANG instead of the default compiler
-DCLANG_CXX_COMPILER=\<clang-bin> | "/usr/bin/clang++" | Set clang C++ compiler binary
-DCLANG_C_COMPILER=\<clang-bin> | "/usr/bin/clang" | Set clang C compiler binary
-DUSE_INTEL=\<BOOL> | FALSE  | Use Intel compiler instead of the default compiler
-DINTEL_CXX_COMPILER=\<clang-bin> | "/opt/intel/bin/icc" | Set Intel C++ compiler binary
-DINTEL_C_COMPILER=\<clang-bin> | "/opt/intel/bin/icpc" | Set Intel C compiler binary


\section min_ct_use Minimal use of the installed ct library 

Once the CT has been built according to \ref build-ros-main or \ref build-cmake-main, the CT libraries are also installed in /usr/lib/ and /usr/include/. We give here an example of how to use the CT library for a new project using CMake. 
The basic project only contains the two following files:

CMakeLists.txt
\code
cmake_minimum_required(VERSION 3.17)

project(my_project)

find_package(ct_optcon REQUIRED)

add_executable(my_project main.cpp)

# Link to libraries
target_link_libraries(my_project PUBLIC ct_optcon)
\endcode

main.cpp

\code
#include <ct/optcon/optcon.h>
#include<iostream>

int main()
{
    const size_t state_dim = ct::core::SecondOrderSystem::STATE_DIM;
    std::cout << "State dim of second order system is " << state_dim << std::endl;
    return 0;
} 
\endcode

Then :
\code{.sh}
mkdir build && cd build
cmake ..
make
./my_project
\endcode

*/
