Get Started
Configuration Options: single phase problems
This guide will help you configure ICLOCS2 for solving optimal control problems direct collocation methods and integrated residual minimization method, with a single phase formulation.
Transcription Method
First we define the transcription methods in
options.transcription='...';
with
 direct_collocation: Direct collocation method
 integral_res_min: Integrated residual minimization method
Note that support for direct multiple shooting is no longer available in ICLOCS version 2.5. Users for Direct Multiple Shooting are adviced to use ICLOCS version 1 or 2, or other better choices e.g. ACADOS.
If the integrated residual minimization method has been selected, please specify the solution method in
options.min_res_mode='...';
with
 alternating: solving integrated residual minimization and objective minimization in an alternating scheme
 weightedCost: using a penalty barrier method with weighted objective
Additionally, for the alternating method, one need to specify the preference in
options.min_res_priority='...';
with
 low_res_error: prefering to obtain a solution with lower integrated residual error
 low_cost_value: prefering to obtain a solution with lower objective value
And for the penalty barrier method, one need to provide a sequence of weigths used for the regularization in
options.resCostWeight='...';
with a sequence 1./(2*[1 0.1 0.01 0.001 ], for example.
Lastly, one need to specify the error criteria in
options.errortype='...';
with
 local_abs: local absolute error (recommended for direct collocation)
 int_res: integrated residual error (recommended for integral residual minimization)
 both: most strict, convergence may be affected (not recommended unless the integrated residual minimization method is selected for result representation)
Discretization Method
As the next category, we can define the discretization methods in
options.discretization='...';
with
 discrete: MPC implementation with discrete time model
 euler: euler discretization
 trapezoidal: trapezoidal discretization
 hermite: HermiteSimpson discretization
 globalLGR: using a single global LGR polynomial of high orders
 hpLGR: using multiple LGR polynomials of various orders
 AutoDirect: Automatic chosen method for direct collocation
Result Representation
Here, we can specify how will the sampled time solution be represented into continuous time trajectories. This can be done in
options.resultRep='...';
with
 default: direct reconstrunction in correspondance with the transcription method (see table for details)

manual: manually select in the options below. For state trajectory
options.stateRep='...';
 linear: Piecewise linear interpolation, available for Euler transcription method only
 quadratic: Piecewise quadratic interpolation, available for Euler and Trapezoidal transcription methods
 cubic: Piecewise cubic interpolation, available for HermiteSimpson transcription method only
 pchip: Piecewise Cubic Hermite Interpolating Polynomial with Matlab pchip function, available for all transcription methods
options.inputRep='...';
 constant: Piecewise constant interpolation, available for all transcription methods
 linear: Piecewise linear interpolation, available for all transcription methods
 quadratic: Piecewise quadratic interpolation, available for HermiteSimpson transcription method only
 pchip: Piecewise Cubic Hermite Interpolating Polynomial with Matlab pchip function, available for all transcription methods
 res_min: Representation by integrated residual minimization (See [1] for details). Requires one additional optimization at each mesh refinement iteration but can obtain solution of higher accuracy for the same mesh.
 res_min_final_default: Final representation by integrated residual minimization (See [1] for details). Requires one additional optimization at the end of the mesh refinement iterations where local error tolerance has been fulfilled. Solution of intermediate mesh refinement itrations represented with default method. Require options.errortype set to 'both'. Can obtain solution of higher accuracy for the same mesh.
 res_min_final_manual: Final representation by integrated residual minimization (See [1] for details). Requires one additional optimization at the end of the mesh refinement iterations where local error tolerance has been fulfilled. Solution of intermediate mesh refinement itrations represented with the manually selected method. Require options.errortype set to 'both'. Can obtain solution of higher accuracy for the same mesh.
If solution by integrated residual minimization has been selected, one can give additional preference for options.resminRep.collmatch to indicate whether to force the endpoint results to be the same from collocation. Also, we can give a tolerance for the cost value with options.resminRep.costTol in precentage (e.g. 0.01 represent maximum increase of 1% of the original cost value).
Derivative generation
The derivative information can be supplied to ICLOCS2 via a number of different ways by setting
options.derivatives='...';
with
 analytic: For simple problems, analytic differentiation may be used for the best computation speed. When this option is selected, the user must additionally supply the following file containing the derived analytical derivatives
 gradCost.m: The gradient of the cost in analytic form
 jacConst.m: The gradient of the plant model, path constraints and boundary constraints (constraint Jacobian)
 hessianLagrangian.m: The Hessian of the Lagrangian
 numeric: For many practical problems, obtaining analytical derivative expressions can be challenging (for example, when lookup tables are used). For these problems, numerical means of supplying the derivative information may be used. When this option is used in ICLOCS2, the Jacobian information will always be calculated with finite difference approximations. As for the Hessian update, the user may futher specify (in the settings later) whether it should supplied with finite differences in ICLOCS2 or fast Hessian update methods (e.g. BFGS) from the NLP solver. The perturbation sizes for numerical differentiation can be (optionally) defined in options.perturbation.J and options.perturbation.H.

adigator: When using finite difference, degradation in accuracy may occur due to numerical errors. One alternative is to
use algorithmic differentiation which is accurate up machine precision. Adigator is a forwardmode algorithmic differentiation toolbox that may be used
for supplying derivative information in ICLOCS2, at a computation cost slightly higher than finite difference. See HERE
for details on obtaining and configuring Adigator. You will need to provide the intallation route of Adigator in
which can be either relative (e.g. '../../adigator') or exact (e.g. 'D:\adigator').
options.adigatorPath='...';
problem.analyticDeriv.gradCost=@gradCost;
problem.analyticDeriv.hessianLagrangian=@hessianLagrangian;
problem.analyticDeriv.jacConst=@jacConst;
NLP solver
Next is to specify the NLP solver
options.NLPsolver='...';
with
 ipopt: The interiorpointmethod based IPOPT solver (recommanded). You may further specify the solver settings (see IPOPT documentations), here we just detail on a few important ones
 options.ipopt.tol: Desired convergence tolerance (relative).
 options.ipopt.max_iter: The maximum number of iterations.
 options.ipopt.hessian_approximation: Indicates what information for the Hessian of the Lagrangian function is used by the solver. Set it to 'exact' to use second derivatives provided by ICLOCS2 (exact Hessian, finite difference and algorithmic differentiation). Alternatively, set it to 'limitedmemory to use the builtin limited memory BFGS update by IPOPT (this is mandatory when multiple shooting method is used).
 fmincon: Use of fmincon is supported but not recommmanded as the solution speed can be significantly slower with a higher chance of failure. Read HERE for further details, otherwise the option will not run!.
 worhp: ICLOCS2 also support the sequential quadratic programming (SQP) solver WORHP up to version 1780 (Later ones do not have Matlab interface). The settings of WORHP solver should be configured with the .xml file in the WORHP package.
Meshing Strategy
ICLOCS 2.5 supports the following options as meshing strategy spcified in
options.meshstrategy='...';
with
 fixed: a fixed mesh
 mesh_refinement: with local refinement of mesh using mesh refinement iterations.
 hp_flexible: flexible mesh with adaptively spaced segments, ONLY AVAILABLE for hpLGR discretization with direct collocation method.
For mesh refinement, it is possible to provide a preference in
options.MRstrategy='...';
with
 aggressive: a relative aggressive scheme that aim to reduce the number of MR iterations and the total MR time
 efficient: a relative aggressive scheme that aim to reduce the size of the problem at the end of MR iterations, making it potentially more efficient for online recomputations.
Furthermore, the maximum number of mesh refinement iterations can be spcified in options.maxMRiter, with the maximum and minimum time interval (in terms of actual time) alled defined in options.mintimeinterval and options.maxtimeinterval repectively.
Lastly, the distribution of integration steps for the fixed mesh or the first iteration of mesh refinement can be spcified in
options.tau='...';
with
 options.tau=0: for equispaced steps
 a vector of length M1 with 0<tau(i)<1 and sum(tau)=1: for a nonuniform mesh.
Other Settings
Hot start
The initial guess of the solving process can be selected by
options.start='...';
with
 Cold: Linear interpolation between the initial point and the final point for the state and input trajectory. No costate/multiplier information supplied.
 Warm: Initial guess of the state and input trajectory interpolated from the solution of previous solve. No costate/multiplier information supplied.
 Hot: Initial guess of the state and input trajectory as well as costate/multipliers interpolated from the solution of previous solve.
Automatic scaling
For problems that contain variables of drastically different numerical ranges (e.g. altitude from 0 to 20000 m but angles only from 6 to 6 rad), automatic scaling is recommanded which may significantly reduce the number of iterations and computation time needed.
options.scaling=1;
Early termination of residual minimization
For use with integrated residual minimization method with the alternating scheme only: setting options.resminEarlyStop=1 allows the residual minimization step to terminate early if the user specified tolerance (in problem.states.xErrorTol_integral) are met, and all constraints are satified.
External Constraint Handling
Setting options.ECH.enabled=1 allows the removal of inactive constraints under a mesh refinement framework, potentially allowing more efficient computations. Additionally, a conservative buffer zone (in percentile, e.g. 0.1) can be specified. See details in [2].
Automatic Regularization Strategy
A regularization parameter could be setup in the problem file with problem.data.penalty.values defining the regularization sequence of weights, and problem.data.penalty.i the starting index. The parameter could be called with vdat.penalty.values(vdat.penalty.i) in problem formulation, with the index i automatically increases from the starting value. Here, multiple strategies are possible interacting with mesh refinement.
 off: Turn off the automatic regularization function.
 reg_priority: Regularization priority: First change regularization paramters iteratively with warm starting resolve, then perform mesh refinement iterations
 MR_priority: Mesh Refinement priority: First perform mesh refinement iterations, then change regularization paramters iteratively with warm starting resolve
 simultaneous: Simultaneous: Perform mesh refinement and regulzarization paramter iterations simultaneously
[1] Y. Nie and E. C. Kerrigan, "Efficient and More Accurate Representation of Solution Trajectories in Numerical Optimal Control," in IEEE Control Systems Letters, vol. 4, no. 1, pp. 6166, Jan. 2020. doi: 10.1109/LCSYS.2019.2921704.
[2] Y. Nie and E. C. Kerrigan, "External Constraint Handling for Solving Optimal Control Problems With Simultaneous Approaches and Interior Point Methods," in IEEE Control Systems Letters, vol. 4, no. 1, pp. 712, Jan. 2020. doi: 10.1109/LCSYS.2019.2921700