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/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.