4. Backward Compatibility¶

FORCESPRO uses continuous deployment as development policy, which may cause also minor new versions not to behave identical to previous ones. This chapter summarizes code-generation options that either recently changed default behavior or were introduced to allow restoring behavior of a previous FORCESPRO version.

4.1. Determining Client Version ¶

For determining the current version of your client, you may invoke the following command:

VER = FORCESversion();

# not yet supported for Python client

The code-generation servers of FORCESPRO only remain available for a certain period of time (but for at least one year after release, see Product Life Cycle). The date when the codegen server of the current client version is planned to go offline can be retrieved as second output argument of the same command:

[VER, OFFLINEDATE] = FORCESversion();

# not yet supported for Python client

4.2. Changes from Version 6.3.0 ¶

From version 6.3.0, the MEX interfaces <solvername>_serialize_mex and <solvername>_deserialize_mex for (de)serializing C parameters return success=1 in case of success and success=0 in case of failure (prior to that version it has been the other way around).

From version 6.3.0, the MEX interface for evaluating the inequality constraints is actually called <solvername>_inequalities as documented in Section Section 9.6 (and not <solvername>_ineq as before).

4.3. Changes from Version 6.2.0 ¶

From version 6.2.0, the BFGS initialization is a field of the model struct instead of the codeoptions. As such, they must be set via model.bfgs_init and not via codeoptions.nlp.bfgs_init anymore. Any existing formulations that still use codeoptions.nlp.bfgs_init would need to be adapted from 6.2.0 onwards. More information on BFGS initialization can be found in Hessian approximation.

From version 6.2.0, the option ADMMfactorize is enabled (= 1) by default for the ADMM solvemethod. The prior default ADMMfactorize = 0 has been deprecated and will be removed completely in a future release.

4.4. Changes from Version 6.1.0 ¶

From version 6.1.0, the default MATLAB dump tool has been changed from legacy dumps to symbolic dumps. In order to continue using the legacy dump tool, you need to explicitly specify ForcesDumpType.LegacyDumpGeneratedC as input argument to the functions ForcesDumpProblem, ForcesDumpFormulation, ForcesDumpAll.

4.5. Changes from Version 6.0.0 ¶

From version 6.0.0, the C interface has changed. The <solvername>_solve function takes as an additional argument the memory buffer containing all solver variables. In order to update to version 6.0.0, you need to extend your C interface according to the following code snippet:

/* additional include required for memory buffer */
#include "<solvername>/include/<solvername>_memory.h"

/* opaque pointer to memory buffer */
<solvername>_mem * mem;
/* Get 0-th memory buffer */
mem = <solvername>_internal_mem(0);
/* call solve function */
exitflag = <solvername>_solve(&params, &output, &info, mem, NULL, extfunc_eval);

If you want full control over memory allocations, or if you require multiple memory buffers (e.g. for running a solver in parallel), you can find more instructions in sections Main Targets and C interface: memory allocations.

Alternatively, you can resort to the legacy C interface equivalent to prior FORCESPRO versions by enabling the compatibility option

codeoptions.legacy_interface = 1

From version 6.0.0, the external function evaluations signature has changed. The new name of the function is <solvername>_adtool2forces (the function name is specific to the solver) and it returns an integer value. The signature is shown below:

int <solvername>_adtool2forces (
    double *x, /* primal vars */
    double *y, /* eq. constraint multipliers */
    double *l, /* ineq . constraint multipliers */
    void *p, /* runtime parameters (passed as void pointer) */
    double *f, /* objective function ( incremented in this function ) */
    double *nabla_f , /* gradient of objective function */
    double *c, /* dynamics */
    double *nabla_c , /* Jacobian of the dynamics ( column major ) */
    double *h, /* inequality constraints */
    double *nabla_h , /* Jacobian of inequality constraints ( column major ) */
    double *H, /* Hessian ( column major ) */
    int stage, /* stage number (0 indexed ) */
    int iteration, /* solver iteration count */
    int threadID /* thread id */
);

4.6. Changes from Version 5.0.1 ¶

From version 5.0.1, license options for FORCESPRO code generation are set in codeoptions.license. Previous options:

codeoptions.useFloatingLicense
codeoptions.license_file_name

have now been replaced by:

codeoptions.license.use_floating_license
codeoptions.license.static_license_file_name

The old options are still available in 5.0.1 for backwards compatibility but the new options override them when set.

4.7. Changes from Version 5.0.0 ¶

From version 5.0.0, FORCESPRO uses CasADi v3.5.5 as default AD tool for both MATLAB and Python client. The following code-generation option can be used for reverting to previous FORCESPRO behavior (since v4.3.0) using CasADi v3.5.1:

codeoptions.nlp.ad_tool = 'casadi-3.5.1'

From version 5.0.0, FORCESPRO uses an improved implementation of the linear solver as default whenever nlp.linear_solver is set to 'symm_indefinite'. The following code-generation option can be used for reverting to previous FORCESPRO behavior:

codeoptions.nlp.linear_solver = 'symm_indefinite_legacy'

From version 5.0.0, FORCESPRO uses RestAPI for server communications. To revert to previous communication methods, the following options can be used (see MATLAB network communications/Python network communications):

codeoptions.server_connection = ForcesWeb.ServerConnections.WSDL
codeoptions.server_connection = ForcesWeb.ServerConnections.WSDL_legacy

codeoptions.server_connection = 'WSDL'

4.8. Changes from Version 4.3.0 ¶

From version 4.3.0, FORCESPRO uses CasADi v3.5.1 as default AD tool for both MATLAB and Python client. The following code-generation option can be used for reverting to previous FORCESPRO behavior using CasADi v2.4.2:

codeoptions.nlp.ad_tool = 'casadi-2.4.2'

4.9. Changes from Version 4.2.0 ¶

From version 4.2.0, the following code-generation options can be used for reverting to previous FORCESPRO behaviors:

codeoptions.legacyNetworkConnections = 1. From version 4.2.0, a new communication method is used to connect to the codegen service for safety and stability reasons. Use this option to use the legacy method of communication.
codeoptions.platform = 'Speedgoat-Legacy-x86'. From version 4.2.0, use this option for Mobile Speedgoat platforms on earlier versions of MATLAB (earlier than R2018b).

From version 4.2.0, the option codeoptions.platform = 'Speedgoat-x86' supports MATLAB versions from R2018b till R2020a, while option codeoptions.platform = 'Speedgoat-QNX' supports MATLAB R2020b and later.

4.10. Changes from Version 4.1.0 ¶

From version 4.1.0, the following code-generation options can be used for reverting to previous FORCESPRO behaviors:

codeoptions.separateCasadiFiles = 1. From version 4.1.0, the old _model files are all gathered in a single _casadi file. Use this option to enable the old behavior, i.e. split model files.
codeoptions.size_one_param_as_array = 1. From version 4.1.0, when using the PDIP_NLP method only, all parameters of size one are treated as scalars by default in order to be compatible with the MATLAB coder. This option enables users to revert to the previous behavior, i.e. scalar parameters as arrays of size one.