Do-mpc

We are finally out of beta with **do-mpc** v4.0.0. Thanks to everyone who has contributed, for the feedback and all the interest.
This release includes some important changes and bugfixes and also significantly extends our homepage [do-mpc](https://do-mpc.com).

We hope you will like the new features and content. Development will now continue with work on version 4.1.0 (and potentially some in between versions with minor features). Stay tuned on our [Github](https://github.com/do-mpc/do-mpc) page and feel free to open issues or join the discussion!

Major changes

New properties for Simulator, Estimator and MPC
Inheriting from the new class `IteratedVariables` these classes now obtain the attributes `_x0`, `_u0`, `_z0` (and `_p_est0`). Users can access these attributes with the properties with `x0`, `u0`, `z0` (and `p_est0`), which are listed in the documentation and have sanity checks etc. when setting them. This fixes e.g. 55.
These new properties are used for two things:
Set initial values
For the simulator the initial state is self explanatory and a very important attribute.
For the `MHE` and `MPC` class the attributes are used when calling the important `set_initial_guess` method, which does exactly that: Set the initial guess of the optimization problem.

Obtain the current values of the iterated variables
This is very useful for conditional MPC loops: E.g. stop the controller and simulation when a certain state has reached a certain value.

Measurement noise
Currently, the `do_mpc.model.Model.set_rhs` method allows to set an additive process noise.
This is used for the MHE optimization problem.
In a similar fashion, the `do_mpc.model.Model.set_meas` method now allows to set an **additive measurement noise.**

In the MHE the measurement noise is introduced as a new optimization variable and the measurement equation is added as an additional constraint.
The full optimization problem now looks like this:
This change makes it possible for the user to decide, which measurements are enforced and which can be perturbed. A typical example would be to ensure that input "measurements" are completely trusted.

Simulator with disturbances
The newly introduced measurement noise and the existing process noise are now used within the simulator. With each call of ``Simulator.make_step`` values can be passed to obtain an imperfectly simulated and measured system..

Documentation
- Release notes are now included in the documentation. They are autogenerated from the Github release notes which can be accessed via Rest API.
- The release notes are appended with a section that includes a download link for the example files that were written for the respective versions.
- Installation instructions now refer to these download links. This solves 62 .
- Added new section **Example gallery**, explaining the supplied examples in **do-mpc** in Jupyter Notebooks (rendered on readthedocs)
- Added new section **Background** with various articles explaining the mathematics behind **do-mpc**.
- Parameter ``collocation_ni`` in MPC/MHE is now explained more clearly.

Minor changes
- Renamed `model.setup_model()` -> `model.setup()`in all examples. This adresses 38
- `opt_p_num` and `opt_x_num` for MHE/MPC are now instance properties instead of class attributes. They still appear in the documentation and can be used as before. Having them as class attributes can lead to problems when multiple classes are live during the same session.

Major changes

Data
- New `__getitem__` method to conveniently retrieve values from `Data` object (details [here](https://github.com/do-mpc/do-mpc/blob/41402152aeb4a2a9b7220434d47c6fa23ca92841/do_mpc/data.py#L75))
- New `MPCData` class (which inherits form `Data`). This adds the `prediction` method, which can be used to query the optimal trajectories. Details [here](https://github.com/do-mpc/do-mpc/blob/41402152aeb4a2a9b7220434d47c6fa23ca92841/do_mpc/data.py#L236).

Both methods were previously (in a slightly different form) in the `Graphics` module. They are still used in this class but can also be convenient under different circumstances.

Graphics
The Graphics module is now initialized with a specific `Data` instance (e.g. `mpc.data`). Each `Data` class has their own `Graphics` class (if it is supposed to be displayed).
Compared to the previous implementation, we now initialize all lines that are supposed to be plotted (and store them in `pred_lines` and `result_lines`). During runtime, the data on these lines is getting updated.

- Added new `structure` class in `do_mpc.tools`. Used for tracking the new `Graphics` properties: `pred_lines` and `result_lines`.
- The properties `pred_lines` and `result_lines` can be used to retrieve line instances with power indices. Line instances can be easily configured (linestyle, alpha, color etc.)

Process noise
Process noise can be added to rhs of `Model` class: [link](https://github.com/do-mpc/do-mpc/blob/3f11da50cb8ab15798411be1c6400753c83d53e4/do_mpc/model.py#L596)

This is solving issue 53 .

This change was necessary to allow for the more natural MHE formulation where the process noise is penalised in the cost function. The user can define for each state (vector) individually if this is intended or not.

As a consequence of this change I had to introduce the new variable `w` throughout **do-mpc**. For the MPC and simulator module this is without effect.

The main difference is [here](https://github.com/do-mpc/do-mpc/blob/3f11da50cb8ab15798411be1c6400753c83d53e4/do_mpc/estimator.py#L573)

**Remark**: The change also allows to estimate parameters that change over time (e.g. environmental influences). Our regular estimated parameters are constant over the entire MHE horizon, which is not always valid. To estimate varying parameters, they should be defined as states with unknown dynamics. Concretely, their RHS is zero (for ODEs) and they have a high process noise.

Symbolic variables for MHE weighting matrices
As originally intended, it is now possible to have symbolic matrices as MHE tuning factors. The result of this change can be seen in the `rotating_oscillating_masses` example.

The symbolic variables are defined in the **do-mpc** `Model` where typically, you want to have `P_x` and `P_p` as parameters and `P_y` and `P_w` as time-varying parameters. Example of their [definition](https://github.com/do-mpc/do-mpc/blob/3f11da50cb8ab15798411be1c6400753c83d53e4/examples/rotating_oscillating_masses_mhe_mpc/template_model.py#L65).

and [here](https://github.com/do-mpc/do-mpc/blob/3f11da50cb8ab15798411be1c6400753c83d53e4/examples/rotating_oscillating_masses_mhe_mpc/template_mhe.py#L51) they are used.

The purpose of using symbolic weighting is of course to update them at each iteration. Since they are parameters and time-varying parameters respectively, this is done with the `set_p_fun` and `set_tvp_fun` method of the `MHE`: [link](https://github.com/do-mpc/do-mpc/blob/3f11da50cb8ab15798411be1c6400753c83d53e4/examples/rotating_oscillating_masses_mhe_mpc/template_mhe.py#L79)

Note that in the example above, we don't actually need varying weighting matrices and the returned values are in fact constant. This can be seen as a proof of concept.

This change had some other implications. Most notably, having additional parameters interferes with the multi-stage robust `MPC` module. Where we previously had to pass
a number of scenarios for each defined parameter.
Since parameters for the MHE are irrelevant for MPC the API for the call `set_uncertainty_values` has changed: [link](https://github.com/do-mpc/do-mpc/blob/3f11da50cb8ab15798411be1c6400753c83d53e4/do_mpc/controller.py#L477)

**The new API is fully backwards compatible.**
However, it is much more intuitive now. The function is called with keyword arguments, where each keyword refers to one uncertain parameter (note that we can ignore the parameters that are irrelevant).
In practice this looks something like [this](https://github.com/do-mpc/do-mpc/blob/3f11da50cb8ab15798411be1c6400753c83d53e4/examples/rotating_oscillating_masses_mhe_mpc/template_mpc.py#L89)

Error in release. Immediately replaced with beta3.

Major changes

* We are now explicitly pointing out attributes of the ``Model`` such as states, inputs, etc. These should be used to obtain these attributes and replace the previous ``get_variables`` method which is now depreciated. The ``Model`` also supports a ``__get_variable__`` call now to conveniently select items.

* ``setup_model`` is replaced by ``setup`` to be more consistent with other setup methods. The old method is still available and shows a depreciation warning.

* The MHE now supports the ``set_default_objective`` method.

Bug fixes

* The MHE formulation had an error in the ``make_step`` method. We used the wrong time step from the previous solution to compute the arrival cost.

Other changes
* Spelling in documentation
* New guide about installing HSL linear solver
* Credits in documentation

**do-mpc** has undergone a massive overhaul and comes with a completely new interface,
new features and a comprehensive documentation.

Please note that previously written code is not compatible with **do-mpc** 4.0.0.
If you want to continue working with older code please use version 3.0.0.

This is the beta release of version 4.0.0. We expect minor modifications and bug fixes in the near future.

Please see our documentation on our new project homepage [www.do-mpc.com](www.do-mpc.com) for a full list of features.