22. Frequently asked questions

22.1. Features of FORCESPRO

  • What problem classes are supported by FORCESPRO?

    FORCESPRO is tailored to solve multistage optimization problems that are either convex (resulting in QP or QCQP problems, see Low-level interface) or non-convex (resulting in NLP problems, see High-level Interface) with continuous optimization variables. In addition, there is somewhat limited support for problems also containing binary or integer variables.

  • Can I use FORCESPRO for non-multistage problems?

    Yes, FORCESPRO supports the case \(N=1\), i.e. a general QCQP of the form

    \begin{align*} \text{minimize} \quad & \frac{1}{2}z^{\top}Hz + f^{\top}z\\ \text{subject to} \quad & Dz = c \\ & \underline{z} \leq z \leq \bar{z} \\ & Az \leq b \\ & z^{\top}Qz + q^{\top}z \leq r \end{align*}

    In order to use this feature, simply call

    stages = MultistageProblem(1);

    and fill in the matrices as described in Low-level interface. The same holds true for single-stage NLP problems.

  • I need to re-linearize the model of my plant at each sampling time. Does FORCESPRO support changing problem matrices during runtime?

    Yes, basically all problem data can be made a real-time parameter and actual values provided during runtime (see section Parametric problems for convex problems and section High-level Interface for passing real-time parameters for a general nonlinear problem).

    When re-linearizing nonlinear dynamics, you obtain in each sampling time a different matrix \(A\), \(B\) and also a new affine part \(g\):

    \[x_{k+1} = Ax_k + Bu_k + g_k\]

    FORCESPRO supports changing these variables at run-time by defining them as parameters.

    Basically the only numerical quantities that need to be fixed during solver generation are the problem dimensions (such as horizon length and number of states/inputs etc.).

  • Which optimization algorithm is used by FORCESPRO?

    FORCESPRO is a code generator that generates optimization solvers that are customized to a specific problem formulation. As the most efficient algorithm typically depends on the exact nature of the problem, various optimization algorithms are provided by FORCESPRO. In particular, implementations of interior-point and first-order methods for convex problems as well as primal-dual interior-point (PDIP) and sequential quadratic programming (SQP) methods for nonlinear problems are offered (see Solve methods).

  • Can FORCESPRO target dSPACE hardware?

    Yes, FORCESPRO can be seamlessly integrated in the dSPACE design flow using its Simulink interface. For more details see dSPACE deployment through Simulink Coder and dSPACE deployment through ConfigurationDesk.

  • Are FORCESPRO solvers thread-safe?

    All solvers comprising only continuous optimization variables are thread-safe indeed (see section Multicore parallelization). Solvers comprising binary or integer variable are currently not thread-safe.

22.2. Setting up a FORCESPRO problem formulation

  • Does my problem formulation need to be smooth? What exactly does this mean?

    Like any derivative-based optimization solver, FORCESPRO solvers work best if all functions defining the optimization problem are sufficiently smooth, i.e. at least continuously differentiable once. FORCESPRO provides a couple of modelling utilities (such as splines) to assist users to formulate smooth problems (see section Modelling Utilities).

    If your problem exhibits non-differentiabilities or even jumps, the solver will often fail to converge.

  • I need a lookup table inside my system dynamics, constraints or objective function. What is the best way to add it?

    In order to yield a smooth formulation, lookup tables need to be approximated or interpolated by a smooth function. FORCESPRO provides dedicated functionality for 1D and 2D splines (see section Modelling Utilities) that can be used anywhere inside a nonlinear problem formulation.

  • Can I formulate convex-quadratic MPC problem using the high-level interface of FORCESPRO?

    The High-level Interface has been designed to formulate general nonlinear optimization problems. If you use it for a formulation that happens to be convex-quadratic, FORCESPRO will typically detect this and will generate a convex solver instead of a nonlinear one. However, this convex solver will be less efficient than the same formulation provided directly via the Low-level interface as certain structure-exploiting features of convex solvers are not yet supported via the high-level interface.

    Finally, note that convexity detection will be bypassed in case the Hessian is provided as a real-time parameter: Since it is not guaranteed to be positive definite in this case, a nonlinear solver is generated, even though the formulation seems convex.

  • When accessing arrays within a problem formulation using the FORCESPRO client, do indices start from 0 or 1?

    All indices for arrays inside the MATLAB client are 1-based. The Python client uses 0-based indices for the high-level interface and, for legacy reasons, 1-based indices for the low-level interface. Further details can be found in section Differences between the MATLAB and the Python client.

22.3. Issues during code generation

  • I get the following error when generating code: `Internal error 0x<something> in FORCESPRO. Please contact support@embotech.com.`

    We are sorry for the inconvenience. While client errors and also most server errors provide meaningful error messages to the user, certain server errors only return an internal error code. In order to help you with this, please send an e-mail to support@embotech.com containing the exact message as well as some information on your problem formulation that caused this error.

  • The code generation process gets stuck displaying `Generating and compiling code…` and sometimes it returns an error after 10 minutes.

    By default, the code is compiled with all compiler optimizations turned on (e.g. -O3). When the size of your code is large, typically when you have a long prediction horizon, it can take a very long time to compile the code with all optimizations turned on. If this process takes too long, the server times out and returns a compilation error. You can reduce the compilation time by reducing the compiler optimization level (see section Compiler optimization level).

  • I am not able to generate a FORCESPRO solver receiving the error `This machine and user do not have a valid license`.

    This means your FORCESPRO license is either not valid or has not been setup correctly. Please make sure that:

    • Your FORCESPRO engineering license has not expired.

    • You have assigned the correct fingerprint of your host machine to your engineering license on the license portal (and this fingerprint has not changed in the meantime).

    • You have entered the correct username in your engineering license on the license portal.

    For further help see https://my.embotech.com/help or write an e-mail to support@embotech.com.

  • I get the following error when generating code: `Server was unable to process request. —> There is no parameter that maps to c of stage 1`. However, according to the multistage formulation, my \(D_1\) is empty in my problem, so \(c_1\) should also be empty.

    We recommend to reformulate the optimization variables for each stage so that \(D_1\) is not empty for performance reasons.

    If this is not possible and \(D_1\) must remain empty, then the inter-stage equality constraint equations become

    \[C_{i-1}z_{i-1} + D_{i}z_{i} = c_{i-1}\]

    instead of

    \[C_{i-1}z_{i-1} + D_{i}z_{i} = c_{i}.\]

  • I get the following error message when generating code: `Error downloading URL. Your network connection may be down or your proxy settings improperly configured.`

    Your current MATLAB configuration is not accepting our website’s SSL certificate. Please follow this link to add our certificate to MATLAB’s list of certificates manually. You can download the embotech certificate using your browser.

  • I get the following error message when generating code: `Invalid MEX-file. The specified module could not be found.`

    Please install the Visual Studio redistributable libraries from here.

  • I get the following error when generating code: `java.io.IOException: Server is not responding, it might not support the current protocol. Missing ServerHello.`

    Some MATLAB versions and some Java installations give problems when communicating using HTTPS from MATLAB. Please edit the file callSoapService.m. Search for the line

    url = URL(endpoint);

    and replace it with

    url = URL([], endpoint, sun.net.www.protocol.https.Handler)

  • I get the following error when generating code: `java.io.IOException: The issuer can not be found in the trusted CA list.`

    Some MATLAB versions and some Java installations give problems when communicating using HTTPS from MATLAB. Please edit the file callSoapService.m. Search for the line

    url = URL(endpoint);

    and replace it with

    url = URL([], endpoint, sun.net.www.protocol.https.Handler)

  • I get the following error when generating code: `javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection?`

    If you are using the enterprise version of FORCESPRO (separate server in your company network), had previously altered the file callSoapService.m to accept secure HTTP connections and the enterprise server is listening on an HTTP port, you receive this error. To fix: Please edit the file callSoapService.m. Search for the line

    url = URL([], endpoint, sun.net.www.protocol.https.Handler)

    and replace it by the default

    url = URL(endpoint);

  • I get the following error message when using the MATLAB interface: `’Unable to cast object of type ‘csmatio.types.MLDouble’ to type ‘csmatio.types.MLStructure’.’`

    Please check that you have your MEX compiler correctly set up. If the problem persists please send your MATLAB and platform settings to support@embotech.com.

22.4. Issues when running a generated solver

  • I am getting exitflag -6, -8 or -10 when running my solver.

    There may be different of reasons depending on your exact formulation, but in general those exitflags point to numerical instabilities. Make sure your problem is reasonably scaled and see the other FAQs.

  • My solver returns exitflag -7.

    Exitflag -7 means that the solver could not proceed. A common cause is the problem being infeasible. FORCESPRO does not have infeasibility detection to speed up the solution time. However, one can

    • in case of a convex problem, use the function stages2qcqp to convert the FORCESPRO problem into a standard (QC)QP that can be given to another QP solver to check for infeasibility (see Debugging a formulation);

    • in case of a general NLP, try formulating the problem with slack variables to make constraints soft to ensure feasibility.

    Another cause for exitflag -7 may be bad scaling of your optimization variables, including unreasonably large bounds.

  • I am getting exitflag -8 when running my SQP solver.

    The underlying QP problem was found to be infeasible. Make sure your problem is reasonably scaled and try increasing the Hessian regularization reg_hessian (see SQP specific codeoptions).

  • I am getting exitflag -6 or -10 when running my nonlinear solver.

    In this case it is a good idea to check that the nonlinear functions provided to the solver are well-defined and that they don’t produce NaNs or Infs. See section Calling the nonlinear functions from MATLAB or Python for how to call the nonlinear functions along with their derivatives directly in MATLAB or Python. If the solver returns exitflag \(-6\), \(-8\) or \(-10\) in the first iteration one needs to check that

    problem.x0

    does not yield NaN or Inf when the nonlinear functions are evaluated on it. E.g. if one has generated a solver named FORCESsolver which does not use any real-time parameters, one needs to check that the following code does not produce an error

    jj = 1;
for ss = 1:model.N
    z = problem.x0[jj:(jj+model.nvar)];
    c, jacc = FORCESsolver_dynamics(z, [], ss);
    ineq, jacineq = FORCESsolver_inequalities(z, [], ss);
    obj, gradobj = FORCESsolver_objective(z, [], ss);
    assert( any(isnan(c) | isinf(c), 'all'), ['Encountered NaNs or Infs in c at stage ', num2str(ss) ]);
    assert( any(isnan(jacc) | isinf(jacc), 'all'), ['Encountered NaNs or Infs in jacc at stage ', num2str(ss) ]);
    assert( any(isnan(ineq) | isinf(ineq), 'all'), ['Encountered NaNs or Infs in ineq at stage ', num2str(ss) ]);
    assert( any(isnan(jacineq) | isinf(jacineq), 'all'), ['Encountered NaNs or Infs in jacineq at stage ', num2str(ss) ]);
    assert( any(isnan(obj) | isinf(obj), 'all'), ['Encountered NaNs or Infs in obj at stage ', num2str(ss) ]);
    assert( any(isnan(gradobj) | isinf(gradobj), 'all'), ['Encountered NaNs or Infs in gradobj at stage ', num2str(ss) ]);
    jj = jj + model.nvar;
end
disp('Did not encounter any NaNs or Infs');

    Note

    See also Real-time SQP Solver: Robotic Arm Manipulator (MATLAB & Python) for an example of how to simulate the dynamics of the system directly in MATLAB and Python.

  • My solver does not perform any iterations and returns exitflag -100 instead.

    This means that the license check for your generated solver failed. Please make sure that:

    • You have assigned the correct fingerprint of the machine on which you are running the solver to your software or hardware testing license on the license portal (and this fingerprint has not changed in the meantime).

    • The license of the machine on which you are running the solver belongs to the same license group as the engineering license used to generate the solver.

    • Your FORCESPRO licenses have not expired.

    • The system clock of your target machine matches universal time (adjusted by correct timezone) quite precisely.

    For further help see https://my.embotech.com/help or write an e-mail to support@embotech.com.

  • ADMM does not converge for my problem.

    The convergence of ADMM depends heavily on the problem scaling. If the matrices for the problem data have very high condition numbers and norms, ADMM can converge extremely slowly regardless of the algorithm parameters. In some cases, ADMM might not converge at all due to severe accumulation of numerical errors. However, often the problem is choosing the right ADMM parameters \(\rho\) and \(\alpha\) to obtain fast convergence of the algorithm.

    If rescaling does not help, try using an interior-point method instead, which is generally more robust and can address numerically more challenging formulations.

  • I am generating code from 32-bit MATLAB. When I run the code it produces a segfault. What is the problem?

    By default, the code is compiled with all optimizations turned on (-O3). We have observed that sometimes there are problems when linking on 32-bit versions of MATLAB. This problem does not occur when the compiler optimization flags are set to -O0, -O1, or -O2. You can change the compiler optimization level by setting the following codeoptions to a value less than 3:

    codeoptions.optlevel = 2;

  • When I run the solver in MATLAB I get the following error: `??? Error using ==> TestSolver freopen of stdout did not work.`

    This is a printing error that occurs in certain old versions of MATLAB because stdout is not defined inside MEX files. Supported versions of MATLAB should not produce this error. You can avoid this error by setting

    codeoptions.printlevel = 0;

22.6. Issues during code deployment

  • I get the following error message when deploying a solver on dSPACE hardware: `OPUS MAKE: Don’t know how to make …`

    This is well-known deployment issue with compiled files. During building for target the compiler is looking for the source code of the solver. The resulting object file is added in the folder <solvername>_<target_ext> which is automatically generated by the compiler. Therefore, to use the object file you need to move it to that folder in order for the compiler to detect it and skip compilation. A possible workaround is to use the static library of the solver as specified in dSPACE deployment through Simulink Coder.

22.7. Other topics

  • Why am I being asked to update the FORCESPRO client software every now and then?

    We have a development policy of continuous deployment, which unfortunately means that we have to ask users to update their clients every time there is a new release of FORCESPRO. To update your client simply type the following in the (MATLAB) command prompt:

    >> updateClient

    For more details see Installation of the MATLAB Client or Installation of the Python Client.

  • How can I obtain information about the KKT conditions at the solution?

    The printlevel solver option allows the user to control how much information is printed by the solver. See here for more information on how to define solver options.

    When printlevel is set to 2 the solver outputs information related to the KKT conditions at every iteration. In particular:

    • res_eq is the maximum \(||C_{i-1}z_{i-1} + D_{i}z_{i}-c_i||_{\infty}\) for all \(i\),

    • If we rewrite all inequality constraints as \(Gz\leq g\) and \(s\) are slack variables for the same constraints, res_ineq is equal to \(||Gz - g + s||_{\infty}\),

    • If \(\lambda\) are the Lagrange multipliers for the inequality constraints, \(\mu\) is equal to \(\lambda^{\top}s\) divided by the number of constraints, i.e. the average complementary slackness.

  • What system information am I sharing by using FORCESPRO?

    When contacting the solver generation server, the FORCESPRO client sends the following system information:

    • Machine username

    • MAC address

    • Fingerprints

    The fingerprint is platform dependent. We create two fingerprints using different system information to create hashes and validate with either of them in order to have a more stable validation:

    • For Windows, each fingerprint uses a subset of the below information:

      • Mac addresses

      • CPU ID (register with machine support)

      • Volume Serial Number

      • Volume GUID

    • For MacOS, each fingerprint uses a subset of the below information:

      • CPU type and CPU subtype

      • Network node hostname

      • Mac addresses

    • For Linux, each fingerprint uses a subset of the below information:

      • Network node hostname

      • /etc/machine-id

      • Mac addresses

      • Linux user uid

    The above information is hashed to create the fingerprint which means that it cannot be recovered by using the fingerprint.

  • I have been using FORCES in the past. Why should I use FORCESPRO?

    The development of the free version of FORCES by ETH (forces.ethz.ch) has been discontinued many years ago, and the code generation service is no longer available.

    The professional version of FORCESPRO comes with professional support, additional interfaces, and a large performance increase.