QpOASES User's Manual - COIN-OR

4m ago
38 Views
0 Downloads
804.66 KB
73 Pages
Transcription

qpOASES User’s ManualVersion 3.2 (April 2017)Hans Joachim Ferreau et al.1,2ABB Corporate Research, [email protected] and present qpOASES developers and contributors in alphabetical order: Eckhard Arnold,Hans Georg Bock, Alexander Buchner, Holger Diedam, Moritz Diehl, Hans Joachim Ferreau, JorisGillis, Boris Houska, Dennis Janka, Christian Kirches, Manuel Kudruss, D. Kwame Minde Kufoalor,Aude Perrin, Andreas Potschka, Milan Vukov, Andreas Waechter, Sebastian F. Walter, ThomasWiese, Leonard Wirsching2qpOASES has been initially released and developed at KU Leuven within the Optimization inEngineering Center (OPTEC), while current development is mainly supported by researchers at theInterdisciplinary Center for Scientific Computing (IWR) at Heidelberg University.

2

Contents1 Introduction1.1 Scope of the Software1.2 Scope of this Manual1.3 Further Support . . .1.4 Citing qpOASES . . .556662 Installation2.1 Standard Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.2 Customised Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.3 Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9910123 Getting Started3.1 Outline . . . . . . . . . . . . .3.2 Main Steps . . . . . . . . . . .3.3 A Tutorial Example . . . . . .3.4 Setting Up Your Own Example.13131316174 Solution Variants for Special QP Types4.1 Solving QPs in Standard Form . . . . . . . . . . . . .4.2 Solving QPs with Varying Matrices . . . . . . . . . . .4.3 Solving Simply Bounded QPs . . . . . . . . . . . . . .4.4 Solving QPs with Positive Semi-Definite Hessian Matrix4.5 Solving QPs with Trivial Hessian Matrix . . . . . . . .4.6 Solving Non-Convex QPs . . . . . . . . . . . . . . . .4.7 Solving QPs with Sparse Matrices . . . . . . . . . . .19192020212324245 Advanced Functionality5.1 Obtaining Status Information . . . . . . . . . . . . . . . . . . . . . . . .5.2 Options for Solving QPs . . . . . . . . . . . . . . . . . . . . . . . . . . .5.3 Specifying a Function for Evaluating the Constraints . . . . . . . . . . .5.4 Initialised Homotopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5.5 Specifying a CPU Time Limit for QP Solution . . . . . . . . . . . . . . .5.6 Providing a Pre-computed Cholesky Factor . . . . . . . . . . . . . . . . .5.7 Further Useful Functionality . . . . . . . . . . . . . . . . . . . . . . . . .5.8 Add-Ons for qpOASES . . . . . . . . . . . . . . . . . . . . . . . . . . . .5.8.1 Solution Analysis . . . . . . . . . . . . . . . . . . . . . . . . . .5.8.2 Solving Test Problems from the Online QP Benchmark Collection.2727283131353536383939.3.

Contents6 Interfaces for Third-Party Software6.1 Interface for Matlab . . . . . . . . . . . . . .6.2 Interface for Simulink . . . . . . . . . . . . .6.3 Interface for Octave . . . . . . . . . . . . . .6.4 Interface for scilab . . . . . . . . . . . . . . .6.5 Interface for Python . . . . . . . . . . . . . . .6.6 Calling qpOASES from Plain C . . . . . . . . .6.7 Running qpOASES on dSPACE . . . . . . . .6.8 Running qpOASES on xPC Target . . . . . . . .6.9 Running qpOASES on Embedded Hardware . . .6.10 Using qpOASES within the ACADO Toolkit6.11 Using qpOASES within MUSCOD-II . . . . .6.12 Using qpOASES within YALMIP . . . . . . . .7 Developer Information and Compiling Options7.1 Class Hierarchy . . . . . . . . . . . . . . . .7.2 Global Constants . . . . . . . . . . . . . . .7.3 Special Types . . . . . . . . . . . . . . . . .7.4 Compiler Flags . . . . . . . . . . . . . . . . .7.5 Unit Testing . . . . . . . . . . . . . . . . . .7.5.1 Testing the C Version . . . . . . .7.5.2 Testing the Matlab Interface . . . graphy64A qpOASES Software Licence654

Chapter 1Introduction1.1Scope of the SoftwareModel predictive control (MPC) is an advanced control strategy which allows to determineinputs of a given process that optimise the forecasted process behaviour. These inputs,or control actions, are calculated repeatedly using a mathematical process model for theprediction. In doing so, the fast and reliable solution of convex quadratic programmingproblems in real-time becomes a crucial ingredient of most algorithms for both linear andnonlinear MPC. The success of linear MPC—where just one quadratic program (QP) needsto be solved at each sampling instant—can even be attributed to the fact that highly efficientand reliable methods for QP solution have existed for decades, and that their computationtimes are much smaller than the required sampling times in typical applications.On the other hand, quadratic programs also arise as sub-problems in sequential quadraticprogramming (SQP) methods, which require not only one but several QPs be solved duringthe iteration. SQP methods can be used for solving general nonlinear programs (NLPs)and are also an established tool for solving nonlinear MPC problems.qpOASES is an open-source implementation of the recently proposed online active set strategy (see [6] and [8]; the main idea has been published earlier for a different class of problemsin [3]). It was inspired by important observations from the field of parametric quadraticprogramming and builds on the expectation that the optimal active set does not changemuch from one quadratic program to the next. It has several theoretical features thatmake it particularly suited for model predictive control applications. The software packageqpOASES implements these ideas and also incorporates important modifications to makethe algorithm numerically more robust [15, 9].qpOASES solving QPs of the following form:minxs. t.1 T2 x Hx xT g(w0 )lbA(w0 ) Ax ubA(w0 ) ,lb(w0 ) x ub(w0 ) ,where the Hessian matrix is symmetric and positive (semi-)definite and the gradient vectoras well as the bound and constraint vectors depend affinely on the parameter w0 .5

Chapter 1. Introduction1.2Scope of this ManualThis manual is organised as follows: first, the installation of the qpOASES software packageis explained in Chapter 2. Afterwards, a concise description of its main functionality isgiven in Chapter 3, which should enable you to use qpOASES within a couple of minutes.Chapter 4 describes special variants for QPs with varying matrices, simply bounded QPsas well as QPs with semi-definite Hessian matrices. Advanced functionality like obtainingstatus information, using the concept of a so-called initialised homotopy or exploiting QPsparsity is discussed in Chapter 5. Various interfaces to third-party software are presentedin Chapter 6. Finally, Chapter 7 (which is mainly intended for software developers) providessome insight into the internal software design of qpOASES, options for further tuning of thealgorithm as well as information on performing unit tests.1.3Further SupportFurther information and user support can be found onhttp://www.qpOASES.org/ , which re-directs tohttps://projects.coin-or.org/qpOASES/ .If you have got questions, remarks or comments on qpOASES, it is strongly encouraged toreport them by creating a new ticket at the qpOASES webpage. In case you do not wantto disclose your feedback to the public, you may send an e-mail [email protected] .Also bug reports, source code enhancements or success stories are most welcome! If youwant to receive latest information on qpOASES or participate in public discussions on futuredevelopments of the code, you should subscribe to the qpOASES mailing list. s/for more details.1.4Citing qpOASESIf you use qpOASES within your scientific work, we strongly encourage you to cite at leastone of the following publications: Reference to the software:@ARTICLE{Ferreau2014,author {H.J. Ferreau and C. Kirches and A. Potschka and H.G. Bock and M. Diehl},title {{qpOASES}: A parametric active-set algorithm for quadratic programming},journal {Mathematical Programming Computation},year {2014},volume {6},number {4},pages {327--363},keywords {qpOASES, parametric quadratic programming, active set method,model predictive control}}6

1.4. Citing qpOASES Reference to the online active set strategy:@ARTICLE{Ferreau2008,author {H.J. Ferreau and H.G. Bock and M. Diehl},title {An online active set strategy to overcome the limitations of explicit MPC},journal {International Journal of Robust and Nonlinear Control},year {2008},volume {18},number {8},pages {816--830},keywords {model predictive control, parametric quadratic programming,online active set strategy}} Reference to the webpage:@MISC{qpOASES2017,author {H.J. Ferreau and A. Potschka and C. Kirches},title {{qpOASES} webpage},howpublished {http://www.qpOASES.org/},year {2007--2017},keywords {qpOASES, model predictive control, parametric quadratic programming,online active set strategy}}AcknowledgementsThe initial version of the software has been partly developed within the framework of the REGINSPREDIMOT European project whose financial support is acknowledged.Further development of the code has been supported by Research Council KUL: CoE EF/05/006Optimization in Engineering Center (OPTEC) and the Research Foundation – Flanders (FWO)where the main author held a 4-years PhD fellowship. Their financial support and permission towork on this open-source software project is gratefully acknowledged.7

8

Chapter 2InstallationThe software package qpOASES is written in an object-oriented manner in C and comesalong with fully commented source code files. Besides some standard C libraries1 no furtherexternal software packages are required. Optionally, the LAPACK and BLAS librariescan be linked for performing internal linear algebra operations.2.1Standard InstallationFor installing qpOASES under Linux, perform the following steps:1. Obtain the latest stable release of qpOASES fromhttps://projects.coin-or.org/qpOASES/ ,either by saving the zipped archive qpOASES-3.2.1.tgz on your local machine or bychecking out the latest stable branch, e.g. by runningsvn co 2from you shell.2. If you obtained a zipped archive, unpack the archive:gunzip qpOASES-3.2.1.tgztar xf qpOASES-3.2.1.tarA new directory qpOASES-3.2.1 will be created. From now on we refer to (the fullpath of) this directory (or the one you used to check out the latest stable branch) by install-dir . It contains seven sub-folders, namely bin (to contain compiled executables and libraries), doc (this manual and a doxygen configuration file), examples (source code of example files for setting up your own QP problems), include (qpOASES header files),1math.h, stdio.h, string.h (as well as sys/time.h, sys/stat.h or windows.h for runtime measurements)9

Chapter 2. Installation interfaces (interfaces to third-party software, see Chapter 6), src (qpOASES source files), testing (basic unit testing, see Section 7.5).3. qpOASES is distributed under the terms of the GNU Lesser General Public Licensev2.1, which you can find in the file install-dir /LICENSE.txt or Appendix Aof this manual. Please read this licence file carefully before you proceed with theinstallation, as you implicitly agree with this licence by using qpOASES!4. If you want to use qpOASES via the provided third-party interfaces only, you can skipthe following steps and proceed as described in Chapter 6. Otherwise continue withtheCompilation of the qpOASES library libqpOASES.a and test examples:cd install-dir makeThis library libqpOASES.a provides the complete functionality of the qpOASES software package. It can be used by, e.g., linking it against a main function from theexamples folder.The make also compiles a couple of test examples; executables are stored within thedirectory install-dir /bin.5. Running a simple test example:Among others, an executable called example1 should have been created; run it inorder to test your installation:cd install-dir /bin./example1If it terminates after successfully solving two QP problems, qpOASES has been successfully installed!6. Optional, create source code documentation2 :cd install-dir /docdoxygen doxygen.configAfterwards, you can open the file install-dir /doc/html/index.html withyour favorite browser in order to view qpOASES’s source code documentation.2.2Customised InstallationInstallation on Windows or Mac OS XIt is also possible to natively install qpOASES on a Windows or Mac OS X machine as itdoes not require any Linux-specific commands. Installation on different operating systemsis facilitated by the following means:2All source code files are commented in a way suitable for the documentation system doxygen [16].10

2.2. Customised Installation1. Customised Makefiles: When calling make, the file install-dir /make.mk isused to select compiler settings that are tailored to different operating systems. Thefollowing settings are provided: make linux.mk, the default choice, for compiling under Linux, make cygwin.mk for compiling under Windows using Cygwin, make windows.mk for compiling under Windows using Microsoft R VisualStudio, make osx.mk for compiling under Mac OS X.Uncomment your preferred choice and run make.2. Compiling with CMake: The file install-dir /CMakeLists.txt configurescompilation on Linux or Windows by means of CMake. We refer to the CMakedocumentation for further details.Static vs. Dynamic LibraryqpOASES can be compiled in