16. Autotuner

The FORCESPRO autotuner is a tool for “tuning” a FORCESPRO solver in an automated way, in order to ensure both robustness and fast convergence on a specific application. Often this means choosing a set of so-called “hyper-parameters” which tailor the algorithm to a specific application.

Important

Currently the FORCESPRO autotuner is only compatible with the SQP Fast algorithm (see Different SQP variants) and the QP Fast algorithm (see The QP_FAST algorithm).

Autotuning a FORCESPRO solver requires setting several tuning options. The tuning options object is constructed by calling ForcesAutotuneOptions which takes as an optional input a cell array of problems instances (here called problems) which are compatible with the generated solver. I.e. each element of the cell array is a struct containing the run-time parameters for a solver:

tuningoptions = ForcesAutotuneOptions(problems);

See Collecting Tuning Data for an explanation of how to collect tuning data (problems) and see section Autotuner Options for which options can be specified through the ForcesAutotuneOptions object. Once the tuning options have been specified a QP_FAST solver (see Tuning the QP_FAST algorithm) can be generated by calling:

ForcesGenerateQpFastSolver(stages,params,codeoptions,tuningoptions,outputs);

and a SQP solver using the fast QP solver (see Different SQP variants) can be generated as follows:

ForcesGenerateSqpFastSolver(model, codeoptions, tuningoptions, outputs);

16.1. Autotuner Options

Via the ForcesAutotuneOptions object, the following options can be set:

  • TuningSeed: Set equal to a non-negative integer to fix the seed in the random number generator used for the FORCESPRO autotuner.

  • TuningMinutes: Number of minutes the tuning should last.

  • TuningIterations: Number of iterations the autotuner should last (only relevant if TuningMinutes = 0). Must be a positive integer.

  • FailureTolerance: Denotes the percentage of problems which are allowed to fail to converge for a tuning to be acceptable. E.g. if FailureTolerance = 0.05 then 5% of problems are allowed to fail to converge. Normally, this value should be kept to 0.

  • ComparisonOutputs: If non-empty, the autotuner will attempt to find a tuning for which the solver produces a solution which is as close to the ones specified here. I.e. the ComparisonOutputs field must be a cell-array of the same length as the cell-array problems passed in the constructor and each element must be of the same type and size as the output which the solver produces.

  • ComparisonObjectives: If non-empty, the autotuner will attempt to find a tuning for which the objective value at the solution produced by the solver matches the one assigned here. In particular, if non-empty, ComparisonObjectives must be a cell-array of the same length as the cell-array problems passed in the constructor.

Several of these options can also be set via the following “setter” methods

  • setTuningGoal: Choose what to tune the solver for. The input to this function must be "speed", "control" or "balanced".

  • setTuningSeed: Set TuningSeed.

  • setTuningMinutes: Set TuningMinutes.

  • setTuningIterations: Set TuningIterations.

16.2. Collecting Tuning Data

The main step in tuning a solver is to collect the tuning data/problems which must be specified directly in the constructor to the ForcesAutotuneOptions class. The standard way to do this is by running one or more simulations with a solver which does not require tuning. In order to see the how to generate such a solver, consult section Tuning the QP_FAST algorithm for the QP Fast solver and Tuning the SQP Fast solver for the SQP Fast solver.

16.3. Validation

The FORCESPRO autotuning tool also allows the user to automatically validate the results the autotuner produces. The purpose of the validation is to check that the tuning found by the autotuner provides a solver which meets the requirements (be it speed or control performance) for a given application. The validation has a default configuration, but can also be configured by setting the following ForcesAutotuneOptions members:

  • ValidationMaxObjTol: Specifies the maximum relative deviation in the optimal objective function value allowed to pass validation of the tuned solver. 0.1 means 10%. Must be a non-negative floating point number. The default value is 0.0, which deactivates the check.

  • ValidationAvgObjTol: Specifies the average relative deviation in the optimal objective function value allowed to pass validation of the tuned solver. 0.1 means 10%. Must be a non-negative floating point number. The default value is 0.1.

  • ValidationMaxControlTol: Specifies the maximum relative deviation in the first optimal control input (2-norm) allowed to pass validation of the tuned solver. 0.1 means 10%. Must be a non-negative floating point number. The default value is 0.0, which deactivates the check.

  • ValidationAvgControlTol: Specifies the average relative deviation in the first optimal control input (2-norm) allowed to pass validation of the tuned solver. 0.1 means 10%. Must be a non-negative floating point number. The default value is 0.1, which deactivates the check.

  • ValidationControlOutputName: Specifies the name of the output at the first stage used to validate the control input accuracy.

  • ValidationControlOutputIdx: Specifies the indices of the variables corresponding to the control inputs at the first stage used to validate the control input accuracy.

Instead of setting these validations directly, one can configure them through the following methods:

  • setValidationControlOutput: Specify the control inputs of the first stage. This method takes ValidationControlOutputName as the first input and ValidationControlOutputIdx as a second input.

  • disableObjValidation: Completely disable validation of the objective function. This method takes no inputs.

  • disableControlValidation: Completely disable the validation of the control performance. This method takes no inputs.

  • disableValidation. Completely disable validation. This method takes no inputs.