1. Introduction

This is a user manual for FORCESPRO, a commercial tool for generating highly customized optimization solvers that can be deployed on all embedded computers. FORCESPRO is intended to be used in situations were the same optimization problem has to be solved many times, possibly in real-time, with varying data, i.e. there is sufficient time in the design stage for generating a customized solution for the problem you want to solve.

../_images/FORCESPro_explanation.png

Figure 1.1 Overview of FORCESPRO.

The code generation engine in FORCESPRO extracts the structure in your optimization problem and automatically synthesizes a custom optimization solver. The resulting C code can only solve one optimization problem (with certain data changing), hence it is typically many times more efficient and smaller code size than general-purpose optimization solvers. The generated C code is also library-free and uses no dynamic memory allocation making it suitable for safe deployment on real-time autonomous systems.

This document will show you how to input your optimization problem description for code generation in FORCESPRO. It is important to point out that FORCESPRO is not a tool for transforming a problem specification into an optimization problem description. This responsibility lies with the user.

1.1. Troubleshooting and support

FORCESPRO typically returns meaningful error messages when code generation errors occur due to invalid user inputs. When encountering other errors please consult our documentation which is included in the FORCESPRO client and is also available on all FORCESPRO servers. In case you cannot find a solution to your problem please submit a bug report to support@embotech.com.

Much effort has gone into making this interface easy to use. We welcome all your suggestions for further improving the usability of the tool. Requests for special functionality for your particular problem will also be considered by our development team. For all requests and feedback please contact support@embotech.com.

1.2. Licensing

1.2.1. Commercial licensing

FORCESPRO licenses are available through a subscription model. There are four types of licenses, as seen below:

  • Engineer License: For generating FORCESPRO solvers. Charged per engineer computer.

  • Software Testing License (Sil/CI): For running FORCESPRO solvers on a desktop PC or a server for simulation and (automated) testing. No physical system is controlled. Charged per platform running the solver.

  • Floating License: For running FORCESPRO solvers on servers or virtualised environments (such as Docker containers) without permanently mapping the license to a hardware system. Charged per number of platforms able to concurrently run the solver. Currently available only on Linux x86/x86_64.

  • Hardware Testing License (HiL/Field Testing): For controlling a physical system (i.e. the target platform may also be an ECU or a rapid prototyping platform). Charged per platform running the solver.

For more information regarding licensing please check on our website or contact sales@embotech.com.

FORCESPRO licenses are available in variants S, M and L. For more information please check the section License Variants

1.2.2. Academic licensing

Users at degree granting institutions can have access to the Engineer License version of FORCESPRO free of charge provided they are not doing research for an industrial partner. Software Testing and Hardware Testing licenses are also available at highly reduced rates.

1.3. Citing FORCESPRO

If you use FORCESPRO in published scientific work, please cite the following two papers:

@misc{FORCESPro,
      Author       = "Alexander Domahidi and Juan Jerez",
      Howpublished = "Embotech AG, url=https://embotech.com/FORCES-Pro",
      Title        = "FORCES Professional",
      Year         = "2014--2019"
}

@article{FORCESNLP,
  Author       = "A. Zanelli and A. Domahidi and J. Jerez and M. Morari",
  Title        = "FORCES NLP: an efficient implementation of interior-point...
                   methods for multistage nonlinear nonconvex programs",
  Journal      = "International Journal of Control",
  Year         = "2017",
  Pages        = "1-17"
  }

1.4. Product Life Cycle

A new major or minor version of FORCESPRO is released every quarter, with patch releases in between. These new versions contain new functionalities and improvements in terms of speed and robustness.

In order to be able to add novel features and improve existing ones at a high pace, FORCESPRO uses continuous deployment as development policy. That also implies that we have to ask users to update their clients if they want to benefit from the latest version of FORCESPRO. In rare cases, this may also mean breaking backward compatibility (see also Section Backward Compatibility) requiring users to either make the necessary changes in their own code or to stick with an older version (and the corresponding server for code generation).

We guarantee that the codegen servers of any new version of FORCESPRO will be kept available for at least one year, starting from their respective release dates. Table 1.1 lists all release dates since version 1.7.0 along with the actual or planned date for the corresponding code generation server to go offline. In case you need an older version of FORCESPRO to be available beyond the scheduled offline date, please contact support@embotech.com so we can work out a solution for you.

Table 1.1 Release Dates and Codegen Server Availabilities

FORCESPRO Version

Release Date

Actual or Planned Date Server goes Offline

1.7.0

2019-03-08

2019-10-01

1.8.0

2019-06-13

2020-04-01

1.9.0

2019-09-05

2020-05-15

1.9.1

2019-10-18

2020-10-01

2.0.0

2019-12-17

2020-12-15

3.0.0

2020-04-09

2021-03-15

3.0.1

2020-05-26

2021-05-31

3.1.0

2020-07-15

2021-07-15

4.0.0

2020-09-22

2021-09-30

4.1.0

2020-11-04

2021-11-15

4.1.1

2020-12-09

2021-12-15

4.2.0

2021-02-11

2022-02-15

4.2.1

2021-03-23

2022-03-31

4.3.0

2021-05-18

2022-05-31

4.3.1

2021-06-01

2022-05-31

4.4.0

2021-06-16

2022-06-30

1.5. Release Notes

1.5.1. New features in FORCESPRO 4.4.0

  • Implemented linear subsystem exploitation for explicit chainrule integrator RK4

  • Implemented chainrule variant for integrator IRK2

  • Added support for dSPACE SCALEXIO and dSPACE MicroLabBox

  • Added functionality to use interpolations (such as splines) inside symbolic problem formulations to both Matlab and Python client

1.5.2. Improvements in FORCESPRO 4.4.0

  • Added Python variant of ForcesMin/ForcesMax, wrapped into new modelling sub-package

1.5.3. Bug Fixes in FORCESPRO 4.4.0

  • Fixed minor issues with return flags of SQP solver, e.g. in case of license error

1.5.4. Improvements in FORCESPRO 4.3.1

  • Added support for server connection via proxy in Python client

1.5.5. Bug Fixes in FORCESPRO 4.3.1

  • Fixed bug for code option threadSafeExpert causing two static variables

  • Added missing code option nlp.max_num_threads to Python client

1.5.6. New features in FORCESPRO 4.3.0

  • Added support to formulate and solve multi-stage nonlinear MPC problems with The MathWorks Model Predictive Control Toolbox (TM)

  • Added code option threadSafeExpert to give users full control over memory allocation when running multiple instances of an PDIP_NLP or PDIP solver

  • Added support for CasADi 3.5.5 in the MATLAB client

1.5.7. Improvements in FORCESPRO 4.3.0

  • Made CasADi 3.5.1 default AD tool also in the MATLAB client

  • Added support for single (stacked) solution vector for solvers PDIP_NLP and SQP_NLP

  • Added more thorough check for identical stages in MATLAB client along with new code option nlp.strictCheckDistinctStages

  • Let FORCESversion also return planned offline date of client version

  • Added new client examples demonstrating how to formulate problems comprising soft and rate constraints using the high-level interface

1.5.8. Bug Fixes in FORCESPRO 4.3.0

  • Fixed freeing of DLLs in Python Client

  • Fixed issue with code option noVariableElimination is used along with linear solver normal_eqs in MATLAB client

1.5.9. Improvements in FORCESPRO 4.2.1

  • Added msgpack support for MacOS

  • Added separate optlevel options for host and target

  • Improved robustness of client connection to the codegen server

  • Added support for custom parameters in Python client

1.5.10. Bug Fixes in FORCESPRO 4.2.1

  • Bugfix in QP solver caused by code optimization for source in src_target folder

  • Fixed bug in ADMM method

1.5.11. New features in FORCESPRO 4.2.0

  • Added support for dumping of problem formulation from C

  • Added support for NI cRIO platforms

  • Created Simulink Fingerprinters for platforms with Simulink Model deployment

  • Added Speedgoat (for MATLAB R2020b and later) example for The MathWorks Model Predictive Control Toolbox (TM)

  • Added support for single precision callbacks, i.e. mixed-precision NLP solution

1.5.12. Improvements in FORCESPRO 4.2.0

  • Changed to new server communication in MATLAB client for improved safety and connection stability

  • Reenabled chainrule integrators as default integrator when using continuous dynamics, and fixed performance issues

  • Extended Speedgoat support to more MATLAB/Simulink Real-Time releases

1.5.13. Improvements in FORCESPRO 4.1.1

  • Improved hashing of sparse linear algebra routines

  • Fixed MATLAB network communication, replaced deprecated SOAP methods with new ones, enabled with legacyNetworkConnections = 0

  • Parallel BFGS updates with compact_code = 0 (default)

  • Prevent MATLAB client to overwrite user script if solver has same filename

  • Throw proper exceptions when block structure is not detected in sparse parametric equalities in low-level interface

  • Parallel callbacks evaluation with compact_code = 1 and parallel >= 1

  • Reverted to legacy integrators in default behaviour

  • Added code generation compatibility with MATLAB 2016a

  • Various fixes and updates in the API of the Python dump tool

1.5.14. Bug Fixes in FORCESPRO 4.1.1

  • Fixed FORCESconfigureClient to work on all OS

  • Fixed codegen failure with compact_code related to nonlinear inequalities

  • Disabled compact_code when initial equality constraint not eliminated (D0)

  • Restored functionality to collect variable declarations at beginning of CasADi callbacks (only if c90 code option is set)

  • Bug fix for copy of scaler parameters with compact_code = 1

1.5.15. New features in FORCESPRO 4.1.0

  • Code-generated explicit integrators and sensitivity with chain rule and variational differential equation

  • Python dump tool and compatible MATLAB dump tool

  • Option for adding a single external callback instead of adding all callbacks externally

  • Added solver and webcompiler support for speedgoat (for MATLAB R2020b and later)

1.5.16. Improvements in FORCESPRO 4.1.0

  • Scalar parameters are not treated as arrays anymore for compatibility with MATLAB Coder. To enable the previous behaviour set code option size_one_param_as_array = 1

  • Separated CasADi and Symbolic math toolbox callbacks to have more control over dynamics callbacks.

  • Introduce code option separateCasadiFiles which when set to 1 ensures old callback file structure (separate model files).

  • Replaced old obstacle avoidance client examples for python and MATLAB by new interactive ones

  • Added path tracking example for the python and the MATLAB client

1.5.17. Bug Fixes in FORCESPRO 4.1.0

  • Fixed Simulink and standalone Python interface using scalar parameters

  • Fixed some openmp issues and added number of threads as runtime parameter

1.5.18. New features in FORCESPRO 4.0.0

  • Support for FORCESPRO NLP solvers (PDIP_NLP and SQP_NLP) in The MathWorks Model Predictive Control Toolbox (TM)

  • Solver timeout option for PDIP_NLP, SQP_NLP and PDIP

  • New code option exportBFGS which enables export of BFGS diagonal on every stage

1.5.19. Improvements in FORCESPRO 4.0.0

  • Server now returns interface/definitions.py file independent of whether the request was sent from the MATLAB or Python client

  • Added support for symbolic step size in Python integrators

  • Added connection tester for the FORCESPRO server

  • Added new parameter type Adense to allow copy of dense A matrix to sparse internally. Should be used within Model Predictive Control Toolbox plugin only!

  • New option nlp.parametricBFGSinit for initializing BFGS matrix as a run-time parameter

1.5.20. Bug Fixes in FORCESPRO 4.0.0

  • Fixed export of root relaxation solution in MINLP solver

  • Fixed number of outputs in ADMM method

  • Added fix for floattype 'int' and 'short'

  • Fixed issue occuring in Python client when all initial or all final variables are fixed

  • Fixed reading issue in csmatio library

1.5.21. New features in FORCESPRO 3.1.0

  • High-level Python interface for NLP solvers

1.5.22. Improvements in FORCESPRO 3.1.0

  • Vectorized outer product on one-stage dense QP problems in double precision on Intel platforms

  • Refactoring of clients and server to enable standalone release

  • Check for vectorization instructions in Python client, refactored C code in DLL

  • Made variables in generated interface static

  • Improved efficiency of CasADi file postprocessing in MATLAB client

  • Export of dual variables in solver PDIP_NLP

  • Fixed updateClient scripts to delete old data

  • Made FORCES_NLP return dumped formulation even if an error occurs during execution

  • Allow to specify directory when saving dumped problem formulation/instance

1.5.23. Bug Fixes in FORCESPRO 3.1.0

  • Fix in detection of selection matrix

  • Fix in CasADi for linux systems

  • Fixed bug with stacked parametric bounds

  • Updated accessing of Stage properties to work with obfuscation

  • fix issue with variable number of equality constraints in convex problems

  • Fixed issue in CasADi code generation

  • Fixed internal rounding heuristic in MINLP solver

1.5.24. Improvements in FORCESPRO 3.0.1

  • New nlp.stack_parambounds for stacking parametric bounds over stages with solvers PDIP_NLP and SQP_NLP

  • Support for MicroAutoBox III

1.5.25. Bug Fixes in FORCESPRO 3.0.1

  • Bug fix in fraction to boundary rule

  • Bug fixes for specific compilation settings

  • Fixed download of CasADi for macos

  • Fixed bug in model files declarations in casadi2forces with solver SQP_NLP

1.5.26. New features in FORCESPRO 3.0.0

  • Real-time sequential quadratic programming solver via code option SQP_NLP

  • Support for MathWorks Symbolic Math Toolbox and CasADi 3.5.1 (with limitations)

  • Code option nlp.compact_code for generating small-size code on long horizon problems

  • Support for license files

  • Option for dumping problem formulation and data for support

1.5.27. Improvements in FORCESPRO 3.0.0

  • Revamped licensing system

  • Removed object files from dowloaded solver package

1.5.28. Bug Fixes in FORCESPRO 3.0.0

  • Fixed bug with number of stages and integer guess in MINLP solver

1.5.29. New features in FORCESPRO 2.0.0

  • Introduced support for FORCESPRO QP solvers in the The MathWorks Model Predictive Control Toolbox (TM)

  • Created new examples for the MPC Toolbox plugin

1.5.30. Improvements in FORCESPRO 2.0.0

  • Made tolerances on equalities, inequalities, stationarity and complementarity run-time parameters in NLP solver

  • Automatic disabling of vectorization when some matrix parameters are sparse

1.5.31. Bug Fixes in FORCESPRO 2.0.0

  • Fixed linking issue with avx on linux host

  • Fixed mex interface to not copy empty parameters

  • Fixed bug with MINLP solver exitflag on infeasible problems

1.5.32. New features in FORCESPRO 1.9.1

  • Adapted FORCESPRO license check to portal database

  • Adapted floating license database checks to portal database

  • Made linear algebra vectorization stage dependent

1.5.33. Improvements in FORCESPRO 1.9.1

  • Fixed numerical bug in NLP line-search

1.5.34. New features in FORCESPRO 1.9.0

  • New code-generation options for AVX and NEON vectorization

  • New code generation options and parameters to provide an integer guess to the MINLP solver

  • New runtime parameter parallelStrategy for MINLP solver

  • Created dedicated Floating License web Server

1.5.35. Improvements in FORCESPRO 1.9.0

  • Changed floating license communication to http

  • Enabled user-defined outputs in MINLP solver

  • Added code option c90 to add extra C definitions in CasADi model files

  • Added openmp flag to nvidia webcompiler

  • Added support for Python 3.6

  • Updated usysid files in client

1.5.36. Bug Fixes in FORCESPRO 1.9.0

  • Fixed bug with constraints handling in code-generation

  • Fixed memory bug in MINLP solver

  • Fixed bug in parameters indexing in client. Parameters are now indexed with a fixed number of digits depending on the horizon length. 1 digit below 10, 2 digits between 10 and 100 excluded,…

  • Fixed bug with stacked parameter ineq.p.b

1.5.37. New features in FORCESPRO 1.8.0

  • Mixed-integer nonlinear solver with parallelizable search and other customization features

  • Support for the Speedgoat platform

  • Support for the Integrity ARM platform

  • Support for Docker containers

  • Updated newParam API to allow for parameters stacked over stages

1.5.38. Improvements in FORCESPRO 1.8.0

  • Improved performance of compactSparse feature

  • Added custom headers to specify platforms

1.5.39. Bug Fixes in FORCESPRO 1.8.0

  • Fixed numerical bug in v1.7.0

1.5.40. New features in FORCESPRO 1.7.0

  • MISRA 2012 compliance, no mandatory or required violations in generated C code

  • Added support for dSPACE MicroAutoBox II

  • Added support for ARM Cortex A72 platforms

  • Added support for MinGW as a mex compiler

  • New code option compactSparse for smaller code and faster compilation of sparse problems

  • Added threadSafeStorage option, enabling creation of thread-safe solvers (requires C11 compilers)

1.5.41. Improvements in FORCESPRO 1.7.0

  • Improved codegen speed for sparse problems

  • Improved web compilation to reduce http timeouts

  • Secure client-server communication under custom embotech domain

  • Improved portability of functions used

  • Added display of license and solver expiration as well as generation id on header files

  • Updated FORCEScleanup to include all solver related files

  • Improved messages and warnings returned from FORCESPRO client

  • Now passing iteration number to function evaluations

  • Added new error code for invalid parameter initial values

1.5.42. Bug Fixes in FORCESPRO 1.7.0

  • Changed default server when default server file is missing

  • Always check for default server files when choosing server to use

  • Corrected the logic for updating the best solution found so far (NLP)

  • Fixed sparse linear algebra routine names

1.6. Version history of manual

The version history of this document is presented in Version history of FORCESPRO manual.

Table 1.2 Version history of FORCESPRO manual

Version

Revision

Date

Reason for change

1

0

2017-04-10

Initial version

2

0

2018-09-27

Overhaul of outdated manual

2

1

2018-11-19

Add dSPACE code deployment

3

0

2019-02-20

Updated manual for v1.7.0

4

0

2019-06-04

Updated manual for v1.8.0

4

1

2019-08-29

Updated manual for v1.9.0

5

0

2019-10-10

Updated manual for v1.9.1

6

0

2019-12-09

Updated manual for v2.0.0

7

0

2020-04-07

Updated manual for v3.0.0

7

1

2020-05-26

Updated manual for v3.0.1

7

2

2020-07-13

Updated manual for v3.1.0

8

0

2020-09-21

Updated manual for v4.0.0

8

1

2020-10-30

Updated manual for v4.1.0

8

2

2020-12-07

Updated manual for v4.1.1

8

3

2021-02-09

Updated manual for v4.2.0

8

4

2021-03-18

Updated manual for v4.2.1

8

5

2021-05-11

Updated manual for v4.3.0

8

6

2021-05-31

Updated manual for v4.3.1

8

7

2021-06-15

Updated manual for v4.4.0