Do-mpc

Fixed an issue with release 4.3.0 where sampling tools where not included on pypi.

Major changes

do-mpc sampling tools

With this release we are integrated a major new feature in do-mpc which was originally started at the [do-mpc developer conference 2021](https://pas.bci.tu-dortmund.de/professorship/news/details/review-do-mpc-developer-conference-13195/).
To learn more about the new feature we have prepared a [video tutorial](https://www.youtube.com/watch?v=3ELyErkYPhE).

Minor changes

- Fixed an issue with saving computation time in MHE/MPC in data object.
- New example: Kite systems

Major changes

Full customization of the MPC or MHE optimization problem is now possible.
Instead of using ``MPC.setup()`` to finalize the MPC optimization problem, an alternative two step process is now possible:
- ``MPC.prepare_nlp()``
- ``MPC.create_nlp()``

In between these two calls, users can add custom constraints and terms to the cost function using state, input etc. variables from different time-steps, collocation points or scenarios.
A typical example would be to constrain changes of inputs or two enforce a cyclic behavior over the course of the horizon.

The new feature is fully documented and we suggest to have a look at the API reference for the MPC or MHE object.

Backend

Model

Internal functions in ``do_mpc.model.Model`` class have now properly named inputs and outputs. These inputs/outputs were previously automatically named ``i0, i1, ...``. They are now name e.g. ``_x, _u, _z ...``.

Here is an example (from the backend):

python
self._rhs_fun = Function('rhs_fun',
[_x, _u, _z, _tvp, _p, _w], [self._rhs], variables
["_x", "_u", "_z", "_tvp", "_p", "_w"], ["_rhs"]) names

This may help for debugging because we now have that:
python
model = do_mpc.model.Model("continuous")
....
model.setup()
print(model._rhs_fun)

Returns

Function(rhs_fun:(_x[6],_u,_z[3],_tvp,_p[2],_w[0])->(_rhs[6]) SXFunction)

Major changes

MX support
This addresses 34.
The do-mpc model class can now be created with the ``symvar_type`` argument, defining whether the model is using CasADi ``SX`` or ``MX`` optimization variables.

python
model = do_mpc.model.Model('continuous', 'MX')


all classes (MPC, MHE, Simulator ...) created from a MX model will also use MX variables.
From a users-perspective the change has no significant influence on the experience.
It does, however, allow for significantly faster matrix vector operations, which is main motivation to use the ``MX`` support.

The new feature resulted in some major changes to the backend.
This is because CasADi does not allow (e.g.):
python
x = MX.sym('x')
struct_symMX([
entry('x', sym=x)
])

on which the model configuration heavily relied on.

Most importantly:
- The Model class attributes ``_x``, ``_u`` etc. are now dicts prior to calling ``Model.setup``.
- Calling ``model['x']`` still works prior to calling ``Model.setup`` but works differently internally
- a new method ``_convert2struct`` converts dicts (e.g. of all the states) to symbolic structures (used in ``Model.setup``). The only problem: These structs hold variables with the same name but which are different.
- a new method ``_substitute_struct_vars`` is introduced and substitutes the variables in the dicts in all expressions (e.g. ``_rhs`` with the new variables from the symbolic structs.
- the MHE also required some major internal changes. The problem is that we split the parameters (``_p``) for the MHE into estimated and set parameters. Splitting symbolic variables with the MX type is problematic.

Minor changes
- Solved 149 : Option to only have a single slack variable (for each soft-constraint) over the entire horizon

Bug fixes
- Resolves 89. Discrete-time model now inherits its properties to MHE/MPC etc.

Major changes

Adapted time-varying parameters for MPC object

Time-varying parameters (tvp) are now defined for ``k=0,...,N+1`` as opposed to ``k=0,...,N`` in the previous version.
The main consequence is that the ``mterm`` for ``mpc.set_objective`` can now include the ``tvp`` in its expression.
This is beneficial e.g. for set-point tracking.

Documentation

Time-varying parameters are also described in greater detail now in [this](https://www.do-mpc.com/en/latest/FAQ.html#time-varying-parameters) article.

Major changes

DAE support
This addresses the long overdue 3 (and closes 36). DAE works for both discrete time and continuous time formulations.

- DAE's are introduced in the model with the [set_alg](https://www.do-mpc.com/en/latest/api/do_mpc.model.Model.set_alg.html) method.
- Algebraic states are introduced with the [set_variable](https://www.do-mpc.com/en/latest/api/do_mpc.model.Model.set_variable.html) method and have the ``var_type='_z'``.
- The model checks that for each newly introduced algebraic state there must be one new algebraic equation. Otherwise the problem is under-determined.
- Algebraic states can be scaled and bounded in both MHE and MPC similar to states, inputs etc. The algebraic equations itself are not automatically scaled. This is different for the ODE which is scaled with the scaling factor for its respective state.

Continuous time (orthogonal collocation)
When using DAEs with continuous time models the DAE equation is added as an additional constraint at each collocation point (both for MHE/MPC).

The simulator must use the ``idas``integration tool (or some other tool supporting DAEs). The default tool ``cvodes`` does not support DAE equations.

Discrete time
When using DAEs with continuous time models the DAE equation is added as an additional constraint at each time-step (both for MHE/MPC).

The simulator cannot simply evaluate the discrete time equation to obtain the next state as it is an expression of the unknown algebraic states. Thus we first solve the algebraic equation with the current state, input etc (using ``nlpsol``) and then evaluate the discrete time equation with the obtained algebraic states.



Constraints with MPC / MHE with orthogonal collocation
Added a flag that can be set during MPC / MHE setup to choose whether [inequality constraints](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.set_nl_cons.html) are evaluated for each collocation point or only on the beginning of the finite Element.
The flag is set during setup of the MPC / MHE with the [set_param](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.set_param.html#do_mpc.controller.MPC.set_param) method:
python
mpc = do_mpc.controller.MPC(model)
setup_mpc = {
'n_horizon': 20,
't_step': 0.005,
'nl_cons_check_colloc_points': True,
}
mpc.set_param(**setup_mpc)

Currently defaults to ``False``.

Added a flag that can be set during MPC / MHE setup to choose whether [bounds](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.bounds.html) (lower and upper) are evaluated for each collocation point or only on the beginning of the finite Element.
The flag is set during setup of the MPC / MHE with the [set_param](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.set_param.html#do_mpc.controller.MPC.set_param) method:
python
mpc = do_mpc.controller.MPC(model)
setup_mpc = {
'n_horizon': 20,
't_step': 0.005,
'cons_check_colloc_points': True,
}
mpc.set_param(**setup_mpc)

Currently defaults to ``True``.

Terminal bounds for MPC
This fixes 35 .
- The MPC controller now supports terminal bounds for the states which can be different to the generic state constraints set with the [bounds](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.bounds.html) attribute.
- Set terminal bounds with the new [terminal_bounds](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.terminal_bounds.html) attribute.
- If no terminal bounds are explicitly set, they default to the regular state bounds (this means that previously working examples won't have to add terminal bounds to obtain the same results).
- If this behavior is undesired (e.g. terminal state should be unbounded even though all other states are bounded) set the parameter ``use_terminal_bounds=False`` during MPC setup.


Minor changes
- ``MPC.set_objective``: The ``mterm`` (terminal cost) now allows parameters (``_p``) in the formulation.
- ``Simulator.set_initial_guess``: Introduced this method to set the initial guess for the algebraic variables. The guess is based on the class attributes ``z0`` which is inline with how the estimator and controller work.
- ``Simulator.make_step``: No longer takes the initial value/guess for ``x0`` and ``z0`` as arguments. The initial state ``x0`` can be changed via its class attribute whereas the initial guess for ``z0`` is changed as described above.
- Adressed 71 : The initial state is no longer constrained through upper and lower bounds.
- Adressed 65 and removed depreciated methods from all modules.

Documentation

- New non-linear example on the front page (double inverted pendulum with obstacle avoidance). This adresses 70.
- Fixed documentation of ``MPC.opt_x_num``. This fixes 72