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/codegen/index.rst b/docs/codegen/index.rst
new file mode 100644
index 0000000..d9ebdc1
--- /dev/null
+++ b/docs/codegen/index.rst
@@ -0,0 +1,46 @@
+Code generation
+===============
+
+OSQP can generate tailored C code that compiles into a fast and reliable solver
+for the given family of QP problems in which the problem data, but not its
+dimensions, change between problem instances.
+
+
+The generated code is:
+
+.. glossary::
+
+ Malloc-free
+ It does not perform any dynamic memory allocation.
+
+ Library-free
+ It is not linked to any external library.
+
+ Division-free
+ There are no division required in the ADMM algorithm
+
+
+We make a distinction between two cases depending on which of the data are to be
+treated as parameters.
+
+.. glossary::
+
+ Vectors as parameters
+ Vectors :math:`q`, :math:`l` and :math:`u` can change between problem instances.
+ This corresponds to the compiler flag :code:`EMBEDDED=1`.
+ :math:`\rho` adaptation is not enabled.
+ The generated code is division-free and has a very small footprint.
+
+ Matrices as parameters
+ Both vectors :math:`q`, :math:`l`, :math:`u` and values in matrices
+ :math:`P` and :math:`A` can change between problem instances.
+ This corresponds to the compiler flag :code:`EMBEDDED=2`.
+ :math:`\rho` adaptation is enabled but the frequency does not rely on any timing.
+ We assume that the sparsity patterns of :math:`P` and :math:`A` are fixed.
+
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
diff --git a/docs/codegen/matlab.rst b/docs/codegen/matlab.rst
new file mode 100644
index 0000000..1b7d0f2
--- /dev/null
+++ b/docs/codegen/matlab.rst
@@ -0,0 +1,168 @@
+Matlab
+======
+
+Before generating code for a parametric problem, the problem should be first
+specified in the setup phase. See :ref:`matlab_setup` for more details.
+
+
+Codegen
+-------
+The code is generated by running
+
+.. code:: matlab
+
+ m.codegen(dir_name, varargin)
+
+The argument :code:`dir_name` is the name of a directory where the generated
+code is stored.
+The second argument :code:`varargin` specifies additional codegen options
+shown in the following table
+
+
++-----------------------+---------------------------------------------------+--------------------------------+
+| Option | Description | Allowed values |
++=======================+===================================================+================================+
+| :code:`project_type` | Build environment | | :code:`''` (default) |
+| | | | :code:`'Makefile'` |
+| | | | :code:`'MinGW Makefiles'` |
+| | | | :code:`'Unix Makefiles'` |
+| | | | :code:`'CodeBlocks'` |
+| | | | :code:`'Xcode'` |
++-----------------------+---------------------------------------------------+--------------------------------+
+| :code:`parameters` | Problem parameters | | :code:`'vectors'` (default) |
+| | | | :code:`'matrices'` |
++-----------------------+---------------------------------------------------+--------------------------------+
+| :code:`mexname` | Name of the compiled mex interface | | :code:`'emosqp'` (default) |
+| | | | Nonempty string |
++-----------------------+---------------------------------------------------+--------------------------------+
+| :code:`force_rewrite` | Rewrite existing directory | | :code:`false` (default) |
+| | | | :code:`true` |
++-----------------------+---------------------------------------------------+--------------------------------+
+| :code:`FLOAT` | Use :code:`float` type instead of :code:`double` | | :code:`false` (default) |
+| | | | :code:`true` |
++-----------------------+---------------------------------------------------+--------------------------------+
+| :code:`LONG` | Use :code:`long long` type instead of :code:`int` | | :code:`true` (default) |
+| | | | :code:`false` |
++-----------------------+---------------------------------------------------+--------------------------------+
+
+You can pass the options as field-value pairs, e.g.,
+
+.. code:: matlab
+
+ m.codegen('code', 'parameters', 'matrices', 'mexname', 'emosqp');
+
+If the :code:`project_type` argument is not passed or is set to :code:`''`,
+then no build files are generated.
+
+
+
+Mex interface
+-------------
+Once the code is generated the following functions are provided through its mex interface. Each function is called as
+
+.. code:: matlab
+
+ emosqp('function_name');
+
+
+where :code:`emosqp` is the name of the mex interface specified in the previous section
+
+.. function:: emosqp('solve')
+ :noindex:
+
+ Solve the problem.
+
+ :returns: multiple variables [x, y, status_val, iter, run_time]
+
+ - **x** (*ndarray*) - Primal solution
+ - **y** (*ndarray*) - Dual solution
+ - **status_val** (*int*) - Status value as in :ref:`status_values`
+ - **iter** (*int*) - Number of iterations
+ - **run_time** (*double*) - Run time
+
+
+.. function:: emosqp('update_lin_cost', q_new)
+ :noindex:
+
+ Update linear cost.
+
+ :param ndarray q_new: New linear cost vector
+
+
+.. function:: emosqp('update_lower_bound', l_new)
+ :noindex:
+
+ Update lower bound in the constraints.
+
+ :param ndarray l_new: New lower bound vector
+
+
+.. function:: emosqp('update_upper_bound', u_new)
+ :noindex:
+
+ Update upper bound in the constraints.
+
+ :param ndarray u_new: New upper bound vector
+
+
+.. function:: emosqp('update_bounds', l_new, u_new)
+ :noindex:
+
+ Update lower and upper bounds in the constraints.
+
+ :param ndarray l_new: New lower bound vector
+ :param ndarray u_new: New upper bound vector
+
+
+If the code is generated with the option :code:`parameters` set to
+:code:`'matrices'`, then the following functions are also provided
+
+
+.. function:: emosqp('update_P', Px, Px_idx, Px_n)
+ :noindex:
+
+ Update nonzero entries of the quadratic cost matrix (only upper triangular) without changing sparsity structure.
+
+ :param ndarray Px: Values of entries to be updated
+ :param ndarray Px_idx: Indices of entries to be updated. Pass :code:`[]` if
+ all the indices are to be updated
+ :param int Px_n: Number of entries to be updated. Used only if Px_idx is not
+ :code:`[]`.
+
+
+.. function:: emosqp('update_A', Ax, Ax_idx, Ax_n)
+ :noindex:
+
+ Update nonzero entries of the constraint matrix.
+
+ :param ndarray Ax: Values of entries to be updated
+ :param ndarray Ax_idx: Indices of entries to be updated. Pass :code:`[]` if
+ all the indices are to be updated
+ :param int Ax_n: Number of entries to be updated. Used only if Ax_idx is not
+ :code:`[]`.
+
+
+.. function:: emosqp('update_P_A', Px, Px_idx, Px_n, Ax, Ax_idx, Ax_n)
+ :noindex:
+
+ Update nonzero entries of the quadratic cost and constraint matrices. It considers only the upper-triangular part of P.
+
+ :param ndarray Px: Values of entries to be updated
+ :param ndarray Px_idx: Indices of entries to be updated. Pass :code:`[]` if
+ all the indices are to be updated
+ :param int Px_n: Number of entries to be updated. Used only if Px_idx is not
+ :code:`[]`.
+ :param ndarray Ax: Values of entries to be updated
+ :param ndarray Ax_idx: Indices of entries to be updated. Pass :code:`[]` if
+ all the indices are to be updated
+ :param int Ax_n: Number of entries to be updated. Used only if Ax_idx is not
+ :code:`[]`.
+
+
+You can update all the nonzero entries in matrix :math:`A` by running
+
+.. code:: matlab
+
+ emosqp('update_A', Ax_new, [], 0);
+
+See C :ref:`C_sublevel_API` for more details on the input arguments.
diff --git a/docs/codegen/python.rst b/docs/codegen/python.rst
new file mode 100644
index 0000000..512ddc3
--- /dev/null
+++ b/docs/codegen/python.rst
@@ -0,0 +1,168 @@
+Python
+======
+
+Before generating code for a parametric problem, the problem should be first
+specified in the setup phase. See :ref:`python_setup` for more details.
+
+
+Codegen
+-------
+The code is generated by running
+
+.. code:: python
+
+ m.codegen(dir_name, **opts)
+
+The argument :code:`dir_name` is the name of a directory where the generated
+code is stored.
+Additional codegen options are shown in the following table
+
++-------------------------+---------------------------------------------------+--------------------------------+
+| Option | Description | Allowed values |
++=========================+===================================================+================================+
+| :code:`project_type` | Build environment | | :code:`''` (default) |
+| | | | :code:`'Makefile'` |
+| | | | :code:`'MinGW Makefiles'` |
+| | | | :code:`'Unix Makefiles'` |
+| | | | :code:`'CodeBlocks'` |
+| | | | :code:`'Xcode'` |
++-------------------------+---------------------------------------------------+--------------------------------+
+| :code:`parameters` | Problem parameters | | :code:`'vectors'` (default) |
+| | | | :code:`'matrices'` |
++-------------------------+---------------------------------------------------+--------------------------------+
+| :code:`python_ext_name` | Name of the generated Python module | | :code:`'emosqp'` (default) |
+| | | | Nonempty string |
++-------------------------+---------------------------------------------------+--------------------------------+
+| :code:`force_rewrite` | Rewrite existing directory | | :code:`False` (default) |
+| | | | :code:`True` |
++-------------------------+---------------------------------------------------+--------------------------------+
+| :code:`FLOAT` | Use :code:`float` type instead of :code:`double` | | :code:`False` (default) |
+| | | | :code:`True` |
++-------------------------+---------------------------------------------------+--------------------------------+
+| :code:`LONG` | Use :code:`long long` type instead of :code:`int` | | :code:`True` (default) |
+| | | | :code:`False` |
++-------------------------+---------------------------------------------------+--------------------------------+
+
+The options are passed using named arguments, e.g.,
+
+.. code:: python
+
+ m.codegen('code', parameters='matrices', python_ext_name='emosqp')
+
+If the :code:`project_type` argument is not passed or is set to :code:`''`,
+then no build files are generated.
+
+
+
+Extension module API
+--------------------
+Once the code is generated, you can import a light python wrapper with
+
+.. code:: python
+
+ import emosqp
+
+where :code:`emosqp` is the extension name given in the previous section. The module imports the following functions
+
+.. py:function:: solve()
+ :noindex:
+
+ Solve the problem.
+
+ :returns: tuple (x, y, status_val, iter, run_time)
+
+ - **x** (*ndarray*) - Primal solution
+ - **y** (*ndarray*) - Dual solution
+ - **status_val** (*int*) - Status value as in :ref:`status_values`
+ - **iter** (*int*) - Number of iterations
+ - **run_time** (*double*) - Run time
+
+
+
+
+
+.. py:function:: update_lin_cost(q_new)
+ :noindex:
+
+ Update linear cost.
+
+ :param ndarray q_new: New linear cost vector
+
+
+.. py:function:: update_lower_bound(l_new)
+ :noindex:
+
+ Update lower bound in the constraints.
+
+ :param ndarray l_new: New lower bound vector
+
+
+.. py:function:: update_upper_bound(u_new)
+ :noindex:
+
+ Update upper bound in the constraints.
+
+ :param ndarray u_new: New upper bound vector
+
+
+.. py:function:: update_bounds(l_new, u_new)
+ :noindex:
+
+ Update lower and upper bounds in the constraints.
+
+ :param ndarray l_new: New lower bound vector
+ :param ndarray u_new: New upper bound vector
+
+
+If the code is generated with the option :code:`parameters` set to
+:code:`'matrices'`, the following functions are also provided
+
+
+.. py:function:: update_P(Px, Px_idx, Px_n)
+ :noindex:
+
+ Update nonzero entries of the quadratic cost matrix (only upper triangular) without changing sparsity structure.
+
+ :param ndarray Px: Values of entries to be updated
+ :param ndarray Px_idx: Indices of entries to be updated. Pass :code:`None` if
+ all the indices are to be updated
+ :param int Px_n: Number of entries to be updated. Used only if Px_idx is not
+ :code:`None`.
+
+
+.. py:function:: update_A(Ax, Ax_idx, Ax_n)
+ :noindex:
+
+ Update nonzero entries of the constraint matrix.
+
+ :param ndarray Ax: Values of entries to be updated
+ :param ndarray Ax_idx: Indices of entries to be updated. Pass :code:`None` if
+ all the indices are to be updated
+ :param int Ax_n: Number of entries to be updated. Used only if Ax_idx is not
+ :code:`None`.
+
+
+.. py:function:: update_P_A(Px, Px_idx, Px_n, Ax, Ax_idx, Ax_n)
+ :noindex:
+
+ Update nonzero entries of the quadratic cost and constraint matrices. It considers only the upper-triangular part of P.
+
+ :param ndarray Px: Values of entries to be updated
+ :param ndarray Px_idx: Indices of entries to be updated. Pass :code:`None` if
+ all the indices are to be updated
+ :param int Px_n: Number of entries to be updated. Used only if Px_idx is not
+ :code:`None`.
+ :param ndarray Ax: Values of entries to be updated
+ :param ndarray Ax_idx: Indices of entries to be updated. Pass :code:`None` if
+ all the indices are to be updated
+ :param int Ax_n: Number of entries to be updated. Used only if Ax_idx is not
+ :code:`None`.
+
+
+You can update all the nonzero entries in matrix :math:`A` by running
+
+.. code:: python
+
+ emosqp.update_A(Ax_new, None, 0);
+
+See C :ref:`C_sublevel_API` for more details on the input arguments.