Squashed 'third_party/osqp/' content from commit 33454b3e23
Change-Id: I056df0582ca06664e86554c341a94c47ab932001
git-subtree-dir: third_party/osqp
git-subtree-split: 33454b3e236f1f44193bfbbb6b8c8e71f8f04e9a
Signed-off-by: Austin Schuh <austin.linux@gmail.com>
diff --git a/docs/get_started/C.rst b/docs/get_started/C.rst
new file mode 100644
index 0000000..18afa57
--- /dev/null
+++ b/docs/get_started/C.rst
@@ -0,0 +1,43 @@
+.. _install_osqp_libs:
+
+CC++
+=====
+
+Binaries
+--------
+
+Precompiled platform-dependent shared and static libraries are available on `GitHub <https://github.com/osqp/osqp/releases>`_.
+We here assume that the user uncompressed each archive to :code:`OSQP_FOLDER`.
+
+Each archive contains static :code:`OSQP_FOLDER/lib/libosqp.a` and shared :code:`OSQP_FOLDER/lib/libosqp.ext` libraries to be used to interface OSQP to any C/C++ software.
+The extension :code:`.ext` is platform dependent and is :code:`.so` for Linux, :code:`.dylib` for Mac and :code:`.dll` for Windows.
+The required include files can be found in :code:`OSQP_FOLDER/include`.
+
+Simply compile with the linker option with :code:`-LOSQP_FOLDER/lib` and :code:`-losqp`.
+
+If you are interested in development builds, you can find them on `GitHub <https://github.com/osqp/osqp/releases>`__.
+
+Sources
+-------
+
+The OSQP libraries can also be compiled from sources. For more details see :ref:`build_from_sources`.
+
+
+Including OSQP in CMake projects
+--------------------------------
+If you compiled OSQP from sources and followed the CMake installation instructions in :ref:`install_the_binaries` section, you can include the package in another CMake project with the following lines depending on whether you need a shared or a static library
+
+.. code::
+
+ # Find OSQP library and headers
+ find_package(osqp REQUIRED)
+
+ # Link the OSQP shared library
+ target_link_libraries(yourTarget PRIVATE osqp::osqp)
+
+ # or...
+
+ # Link the OSQP static library
+ target_link_libraries(yourTarget PRIVATE osqp::osqpstatic)
+
+
diff --git a/docs/get_started/cutest.rst b/docs/get_started/cutest.rst
new file mode 100644
index 0000000..c3de773
--- /dev/null
+++ b/docs/get_started/cutest.rst
@@ -0,0 +1,12 @@
+CUTEst
+=======
+
+To be able to use OSQP and `CUTEst <https://github.com/ralna/CUTEst/wiki>`_ you need to
+
+* Install `CUTEst <https://github.com/ralna/CUTEst/wiki>`_
+* Compile :ref:`OSQP from sources <build_from_sources>`
+* Set the environment variable :code:`OSQP` to the main OSQP directory containing source code for which the compiled binary libraries lie in :code:`$OSQP/build/out`.
+
+For more details, see the `README.osqp <https://github.com/ralna/CUTEst/blob/master/src/osqp/README.osqp>`_ file in the CUTEst repository.
+
+
diff --git a/docs/get_started/index.rst b/docs/get_started/index.rst
new file mode 100644
index 0000000..266222a
--- /dev/null
+++ b/docs/get_started/index.rst
@@ -0,0 +1,17 @@
+Get started
+===============
+
+To get started simply choose your language interface and follow the easy installation instructions below:
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ sources.rst
+ C.rst
+ python.rst
+ julia.rst
+ matlab.rst
+ r.rst
+ cutest.rst
+ linear_system_solvers.rst
diff --git a/docs/get_started/julia.rst b/docs/get_started/julia.rst
new file mode 100644
index 0000000..0acea0d
--- /dev/null
+++ b/docs/get_started/julia.rst
@@ -0,0 +1,12 @@
+Julia
+======
+
+Julia interface can be directly installed from Julia package manager by running
+
+.. code:: julia
+
+ ] add OSQP
+
+
+The interface code is available on `GitHub <https://github.com/osqp/OSQP.jl>`_.
+
diff --git a/docs/get_started/linear_system_solvers.rst b/docs/get_started/linear_system_solvers.rst
new file mode 100644
index 0000000..0cbb1c9
--- /dev/null
+++ b/docs/get_started/linear_system_solvers.rst
@@ -0,0 +1,72 @@
+.. _linear_system_solvers_installation :
+
+Linear System Solvers
+======================
+
+The linear system solver is a core part of the OSQP algorithm.
+Depending on the problem instance, different linear system solvers can greatly speedup or reduce the computation time of OSQP.
+To set the preferred linear system solver, see :ref:`linear_system_solvers_setting`.
+
+Dynamic shared library loading
+------------------------------
+OSQP dynamically loads the shared libraries related to the selected external solver. Thus, there is no need to link it at compile time.
+The only requirement is that the shared library related to the solver is in the library path of the operating system
+
++------------------+---------------------------+----------------+
+| Operating system | Path variable | Extension |
++==================+===========================+================+
+| Linux | :code:`LD_LIBRARY_PATH` | :code:`.so` |
++------------------+---------------------------+----------------+
+| Mac | :code:`DYLD_LIBRARY_PATH` | :code:`.dylib` |
++------------------+---------------------------+----------------+
+| Windows | :code:`PATH` | :code:`.dll` |
++------------------+---------------------------+----------------+
+
+
+
+
+
+QDLDL
+---------------
+OSQP comes with `QDLDL <https://github.com/osqp/qdldl>`_ internally installed.
+It does not require any external shared library.
+QDLDL is a sparse direct solver that works well for most small to medium sized problems.
+However, it becomes not really efficient for large scale problems since it is not multi-threaded.
+
+
+MKL Pardiso
+-----------
+`MKL Pardiso <https://software.intel.com/en-us/mkl-developer-reference-fortran-intel-mkl-pardiso-parallel-direct-sparse-solver-interface>`_ is an efficient multi-threaded linear system solver that works well for large scale problems part of the Intel Math Kernel Library.
+Intel offers `free lincenses <https://software.intel.com/en-us/articles/free-mkl>`_ for MKL for most non-commercial applications.
+
+Install with MKL
+^^^^^^^^^^^^^^^^
+We can install MKL Pardiso by using the standard `MKL installer <https://software.intel.com/en-us/mkl>`_.
+The main library to be loaded is called :code:`libmkl_rt`.
+To add it, together with its dependencies, to your path, just execute the automatic MKL script.
+
++------------------+------------------------------------------------+
+| Operating system | Script |
++==================+================================================+
+| Linux | :code:`source $MKLROOT/bin/mklvars.sh intel64` |
++------------------+------------------------------------------------+
+| Mac | :code:`source $MKLROOT/bin/mklvars.sh intel64` |
++------------------+------------------------------------------------+
+| Windows | :code:`%MKLROOT%\mklvars.bat intel64` |
++------------------+------------------------------------------------+
+
+where :code:`MKLROOT` is the MKL installation directory.
+
+Install with Anaconda
+^^^^^^^^^^^^^^^^^^^^^
+`Anaconda Python distribution <https://www.anaconda.com/download/>`_ comes with the intel MKL libraries preinstalled including MKL Pardiso.
+To use this version, the Anaconda libraries folders have to be in your system path.
+Anaconda environments should add them automatically so in most cases you do not have to do anything. If you get an error where OSQP cannot find MKL, you can add the right path by adding the output from the following command to your path variable:
+
+.. code::
+
+ echo "`ls -rd ${CONDA_ROOT}/pkgs/*/ | grep mkl-2 | head -n 1`lib:`ls -rd ${CONDA_ROOT}/pkgs/*/ | grep intel-openmp- | head -n 1`lib"
+
+
+where :code:`ANACONDA_ROOT` is the root of your anaconda installation.
+
diff --git a/docs/get_started/matlab.rst b/docs/get_started/matlab.rst
new file mode 100644
index 0000000..e8e58ea
--- /dev/null
+++ b/docs/get_started/matlab.rst
@@ -0,0 +1,60 @@
+Matlab
+======
+OSQP Matlab interface requires Matlab 2015b or newer.
+
+
+Binaries
+--------
+
+Precompiled platform-dependent Matlab binaries are available on `GitHub <https://github.com/osqp/osqp-matlab/releases>`_.
+
+To install the interface, just run the following commands:
+
+.. code:: matlab
+
+ websave('install_osqp.m','https://raw.githubusercontent.com/osqp/osqp-matlab/master/package/install_osqp.m');
+ install_osqp
+
+
+Sources
+-------
+
+You need to install the following (see :ref:`build_from_sources` for more details):
+
+- A supported 64bit `C/C++ compiler <https://www.mathworks.com/support/compilers.html>`_
+- `CMake <https://cmake.org/>`_
+
+
+
+After you install both, check that your compiler is selected by executing
+
+.. code:: matlab
+
+ mex -setup
+
+.. note::
+
+ **Windows**: If Matlab does not find TDM-GCC, you need to set the environment variable :code:`MW_MINGW64_LOC` as follows
+
+ .. code:: matlab
+
+ setenv('MW_MINGW64_LOC', 'C:\TDM-GCC-64')
+
+
+ where :code:`C:\TDM-GCC-64` is the installation folder for TDM-GCC.
+
+You can now build the interface by running inside Matlab
+
+.. code:: matlab
+
+ !git clone --recurse-submodules https://github.com/osqp/osqp-matlab
+ cd osqp-matlab
+ make_osqp
+
+
+Then you can add the interface to the search path by executing from the same directory
+
+.. code:: matlab
+
+ addpath(pwd)
+ savepath
diff --git a/docs/get_started/python.rst b/docs/get_started/python.rst
new file mode 100644
index 0000000..a29e0eb
--- /dev/null
+++ b/docs/get_started/python.rst
@@ -0,0 +1,44 @@
+Python
+======
+
+Python interface supports Python 2.7 and 3.5 or newer.
+
+Pip
+----
+
+.. code:: bash
+
+ pip install osqp
+
+
+Anaconda
+--------
+
+.. code:: bash
+
+ conda install -c conda-forge osqp
+
+
+Sources
+---------
+You need to install the following (see :ref:`build_from_sources` for more details):
+
+- `GCC compiler <https://gcc.gnu.org/>`_
+- `CMake <https://cmake.org/>`_
+
+.. note::
+
+ **Windows**: You need to install **also** the Visual Studio C++ compiler:
+
+ * Python 2: `Visual C++ 9.0 for Python (VC 9.0) <https://www.microsoft.com/en-us/download/details.aspx?id=44266>`_
+
+ * Python 3: `Build Tools for Visual Studio 2017 <https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017>`_
+
+
+Now you are ready to build OSQP python interface from sources. Run the following in your terminal
+
+.. code:: bash
+
+ git clone --recurse-submodules https://github.com/osqp/osqp-python
+ cd osqp-python
+ python setup.py install
diff --git a/docs/get_started/r.rst b/docs/get_started/r.rst
new file mode 100644
index 0000000..a8fb63f
--- /dev/null
+++ b/docs/get_started/r.rst
@@ -0,0 +1,40 @@
+R
+======
+
+Binaries
+--------
+
+A pre-compiled version of the OSQP R interface can be installed directly from within R. Note that this will install the OSQP interface from the current CRAN repository, which may not be the most up-to-date version:
+
+.. code:: r
+
+ install.packages("osqp")
+
+
+
+The pre-compiled binaries can also be downloaded `directly from the CRAN server
+<https://cran.r-project.org/web/packages/osqp/>`_.
+
+From Sources
+------------
+
+If you would like to use the most recent version of OSQP-R and have access to git on your machine along with a suitable compiler, then you can do the following from within a terminal:
+
+.. code:: r
+
+ git clone --recursive https://github.com/osqp/osqp-r.git
+ cd osqp-r
+ R CMD install .
+
+From Sources (within R)
+-----------------------
+
+If you would like to install the latest version directly from with R (e.g.\ because you do not have ``git`` installed) and have a suitable compiler, then you can do the following from within R:
+
+.. code:: r
+
+ install.packages("remotes")
+ remotes::install_github("r-lib/remotes#103")
+ remotes::install_git("git://github.com/OxfordControl/osqp-r",submodules = TRUE)
+
+Note that the second line above is necessary because the "remotes" package in R does not currently support recursive cloning of git submodules.
diff --git a/docs/get_started/sources.rst b/docs/get_started/sources.rst
new file mode 100644
index 0000000..760ae3b
--- /dev/null
+++ b/docs/get_started/sources.rst
@@ -0,0 +1,137 @@
+.. _build_from_sources:
+
+
+Build from sources
+==================
+
+Install GCC and CMake
+----------------------
+
+The main compilation directives are specified using
+
+- `GCC compiler <https://gcc.gnu.org/>`_ to build the binaries
+- `CMake <https://cmake.org/>`__ to create the Makefiles
+
+
+Linux
+^^^^^
+Both :code:`gcc` and :code:`cmake` commands are already installed by default.
+
+Mac OS
+^^^^^^
+
+Install Xcode and command line tools
+""""""""""""""""""""""""""""""""""""
+
+#. Install the latest release of `Xcode <https://developer.apple.com/download/>`_.
+
+#. Install the command line tools by executing from the terminal
+
+ .. code:: bash
+
+ xcode-select --install
+
+Install CMake via Homebrew
+"""""""""""""""""""""""""""
+
+#. Install `Homebrew <https://brew.sh/>`_ and update its packages to the latest version.
+
+#. Install cmake by executing
+
+ .. code:: bash
+
+ brew install cmake
+
+
+Windows
+^^^^^^^
+
+#. Install `TDM-GCC <http://tdm-gcc.tdragon.net/download>`_ 32bit or 64bit depending on your platform.
+
+#. Install the latest binaries of `CMake <https://cmake.org/download/#latest>`__.
+
+
+Build the binaries
+------------------
+
+Run the following commands from the terminal
+
+#. You first need to get the sources from one of these two options:
+
+ * Download the compressed source file from the latest OSQP release `at GitHub <https://github.com/osqp/osqp/releases>`_.
+
+ * Clone the repository
+
+ .. code:: bash
+
+ git clone --recursive https://github.com/osqp/osqp
+
+#. Create :code:`build` directory and change directory
+
+ .. code:: bash
+
+ cd osqp
+ mkdir build
+ cd build
+
+#. Create Makefiles
+
+ - In Linux and Mac OS run
+
+ .. code:: bash
+
+ cmake -G "Unix Makefiles" ..
+
+ - In Windows run
+
+ .. code:: bash
+
+ cmake -G "MinGW Makefiles" ..
+
+
+#. Compile OSQP
+
+ .. code:: bash
+
+ cmake --build .
+
+
+Thanks to CMake, it is possible to create projects for a wide variety of IDEs; see `here <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_ for more details. For example, to create a project for Visual Studio 14 2015, it is just necessary to run
+
+.. code:: bash
+
+ cmake -G "Visual Studio 14 2015" ..
+
+
+The compilation will generate the demo :code:`osqp_demo` and the unittests :code:`osqp_tester` executables. In the case of :code:`Unix` or :code:`MinGW` :code:`Makefiles` option they are located in the :code:`build/out/` directory. Run them to check that the compilation was correct.
+
+
+Once the sources are built, the generated static :code:`build/out/libosqp.a` and shared :code:`build/out/libosqp.ext` libraries can be used to interface any C/C++ software to OSQP (see :ref:`install_osqp_libs` installation).
+
+.. _install_the_binaries:
+
+Install the binaries
+--------------------
+
+
+
+To install the generated libraries and headers to a system-wide location compatible with `GNU standards <http://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_ it is just necessary to run
+
+.. code:: bash
+
+ cmake --build . --target install
+
+This code installs the libraries in :code:`libdir` and the headers into :code:`includedir/osqp`. For mode details see the defaults folders on the `GNU standards <http://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_ website.
+To change the installation prefix, in the "Create Makefiles" step above, you need to specify the destination folder as :code:`cmake -DCMAKE_INSTALL_PREFIX:PATH=myfolder ..`.
+
+.. note:: This step requires write permissions in the destination
+ folders. You might be able to gain access using the
+ :code:`sudo` command.
+
+We provided also an uninstall routine to remove the copied files by running
+
+.. code:: bash
+
+ cmake --build . --target uninstall
+
+Note that this corresponds to running :code:`make install` and :code:`make uninstall` on unix machines.