# Release notes
This content is autogenereated from our Github [release notes](https://github.com/do-mpc/do-mpc/releases).
## v5.1.0
### Release Notes

#### Major Changes

##### Integer Variable Support
do-mpc now supports integer variables for Mixed Integer Nonlinear Programming (MINLP). Variables must be declared as integer during model creation. The MINLP problems are solved using the [BONMIN](https://www.coin-or.org/Bonmin/) solver. See the [documentation](https://www.do-mpc.com/en/latest/api/do_mpc.model.Model.html#set-variable) and the new [example](https://github.com/do-mpc/do-mpc/tree/master/examples/Lotka_Volterra) for implementation details.

##### PyTorch Installation Changes
PyTorch is no longer included in the default installation to keep the package size small for users who don't need the ApproximateMPC feature. To use the [ApproximateMPC](https://www.do-mpc.com/en/latest/api/do_mpc.approximateMPC.html) feature, install the full package:
```
pip install do_mpc[full]
```

#### Minor Changes

##### R-term Scaling for Multi-stage MPC
Fixed R-term [scaling](https://github.com/do-mpc/do-mpc/blob/master/do_mpc/controller/_mpc.py#L1197) in multi-stage MPC formulations. Previously, the R-term was not scaled by the number of scenarios, causing its influence on the optimizer solution to increase with scenario count.

##### Bug Fixes and Testing
- FIxed a bug that caused an offset between simulator and MPC when visualizing tvp's.
- Added new unit test

#### Upgrading

Users relying on ApproximateMPC should update their installation command to include the full extras:
```
pip install --upgrade do_mpc[full]
```
## v5.0.1
##### Bug Fixes

- **Fixed ImportError for approximateMPC module** 
  - Added missing `do_mpc.approximateMPC` package to `setup.py`
  - Module can now be imported correctly after pip installation

**Please see the notes of release v5.0.0.**
## v5.0.0
### do-mpc v5.0.0

We are happy to announce the release of do-mpc v5.0.0. Thanks to everyone who has contributed, for the feedback and all the interest.

This release introduces **Approximate MPC** as a machine learning-based approximation of the MPC class, enabling MPC deployment in systems where real-time optimization is not feasible. Our goal with this feature is to provide an easy-to-use interface that requires no expert knowledge while still allowing users to customize the model and training process. Additionally, we introduce the **Extended Kalman Filter** as the newest addition to our state estimators.

We hope you will like the new features and content. Development will now continue with enhancements to the Approximate MPC feature and the implementation of parameter estimation in version 5.1.0. 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

##### Approximate MPC

Approximate MPC uses an artificial neural network trained to approximate an MPC controller. It predicts the optimal control action based on the current state of the system. This feature introduces the following classes to do-mpc:

- **[ApproxMPC](https://www.do-mpc.com/en/latest/api/do_mpc.approximateMPC.ApproxMPC.html)**: A class to configure and run the ApproxMPC controller based on a previously configured [`do_mpc.controller.MPC`](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.html#do_mpc.controller.MPC) instance.
- **[FeedforwardNN](https://www.do-mpc.com/en/latest/api/do_mpc.approximateMPC.FeedforwardNN.html)**: A class to set up a PyTorch neural network used by the ApproxMPC class.
- **[Trainer](https://www.do-mpc.com/en/latest/api/do_mpc.approximateMPC.Trainer.html)**:  A class for training the ApproxMPC.
- **[AMPCSampler](https://www.do-mpc.com/en/latest/api/do_mpc.approximateMPC.AMPCSampler.html)**: A class to sample data for the ApproxMPC using do-mpc's existing [sampling planner](https://www.do-mpc.com/en/latest/api/do_mpc.sampling.SamplingPlanner.html).

After setup, the ApproxMPC class can be used like a [`do_mpc.controller.MPC`](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.html) instance in a closed-loop setting by calling the [`make_step()`](https://www.do-mpc.com/en/latest/api/do_mpc.approximateMPC.ApproxMPC.html#make-step) method. This method takes the current state `x0` of the system and returns the control action `u0`.

For a detailed introduction to the setup and application of the Approximate MPC feature, we provide a new [example notebook](https://www.do-mpc.com/en/latest/example_gallery/appx_cstr_example.html).

##### Extended Kalman Filter

The Extended Kalman Filter (EKF) is now available as a state estimator option alongside the existing Moving Horizon Estimator (MHE).

Like the [MHE](https://www.do-mpc.com/en/latest/api/do_mpc.estimator.MHE.html), the [EKF](https://www.do-mpc.com/en/latest/api/do_mpc.estimator.EKF.html) class is built upon our [Estimator](https://www.do-mpc.com/en/latest/api/do_mpc.estimator.Estimator.html) base class, making it fit seamlessly into the existing do-mpc framework. When used with nonlinear systems, do-mpc computes linearized system matrices under the hood. The current EKF implementation works with discrete and continuous models. It can be used to estimate differential states `x`. Models with algebraic states `z` are currently not supported.

For a detailed introduction to the setup and application of the EKF state estimator, we provide a new [example implementation](https://github.com/do-mpc/do-mpc/tree/master/examples/triple_tank_ekf).

##### Documentation 
As always, we keep our [documentation ](https://www.do-mpc.com/en/latest/index.html)up to date, which contains detailed documentation for all new classes of do-mpc.
#### Minor changes

- Scaling methods for the [Simulator class](https://www.do-mpc.com/en/latest/api/do_mpc.simulator.Simulator.html#do_mpc.simulator.Simulator.scaling).
- New examples including a triple tank system [example implementation](https://github.com/do-mpc/do-mpc/tree/master/examples/triple_tank_ekf) and a [kinematic bicycle model](https://github.com/do-mpc/do-mpc/tree/master/examples/kinematic_bicycle_model)
- [Example code](https://github.com/do-mpc/do-mpc/tree/master/examples/tools/pytorch_2_do-mpc) demonstrating how to use a PyTorch model in do-mpc
- do-mpc 5.0.0 is tested for Python 3.10, 3.11, and 3.12
- Version restrictions for Numpy removed
## v4.6.5
### Minor changes

This release is a response to the release of Numpy 2.0.0. Until all version conflicts are resolved, Numpy is restricted to `numpy<2.0.0`.

#### Further changes are:

- The `opts` dictionary in simulator.py is now initialized correctly when `collocation` is selected as integration tool
- importlib.util is now imported correctly when importing do-mpc 

## v4.6.4
##### Release notes
Please see the notes of release v4.6.3.
## v4.6.3
##### Minor changes

- The penalty term (`rterm`) of the MPC formulation can now be customized. For more information, see the [documentation](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.html#set-rterm)
- All CasADI integrator options can now be accessed via the `simulator.settings` syntax. For more information see the [documentation](https://www.do-mpc.com/en/latest/api/do_mpc.simulator.ContinousSimulatorSettings.html#do_mpc.simulator.ContinousSimulatorSettings) 
- The `settings `attribute of the `MPC `and `Simulator `classes is now called `_settings`. It can be accessed via the `settings `method. The user interface remains identical.
- Minor bug fixes in the documentation an the `Simulator `class
## v4.6.2
### Minor changes

- Added new settings attribute in `_mpc.py`
- Added citation file
## v4.6.1
### Minor changes
- Fixed #387 
- ``do-mpc`` can now be installed either as:
```
pip install do_mpc
```
or 
```
pip install do_mpc[full]
```
Only with the full installation, optional features are available, e.g.:
- ONNX conversion
- OPCUA 

### Backend changes
- Fixed readthedosc configuration according to the new [specification](https://docs.readthedocs.io/en/stable/config-file/v2.html)
-  New setup for requirement files (splitting the pip requirements files according to this [description](https://stackoverflow.com/questions/11704287/split-requirements-files-in-pip)):
    - ``requirements.txt`` lists the base requirements for the do-mpc core features.
    - ``requirements_full.txt`` is a superset of requirements and includes optional do-mpc features (e.g. ONNX conversion).
    - ``requirements_docs.txt`` is a superset of the full requirements and includes the packages required to build the docs.

## v4.6.0
### Major changes

For detailed information on the major changes, please visit our website [www.do-mpc.com](https://www.do-mpc.com/en/latest/).

#### OPC UA module
Building on the [opcua-asnycio](https://github.com/FreeOpcUa/opcua-asyncio) library, do-mpc now facilitates plant communication and software-in-the-loop testing with OPC UA. 
- Core MPC modules can automatically derive and OPC UA client
- A local OPC UA server can be configured with namespace derived from clients for testing purposes


#### Interoperability with deep learning toolboxes through ONNX
``do-mpc`` now supports the open neural network exchange  ([ONNX](https://onnx.ai)) standard.
- Incorporate neural networks previously trained in Tensorflow, Pytorch, Matlab, etc. (with an option to export ONNX models)
- Convert ONNX models to CasADi expressions (the backbone of ``do-mpc``).  

#### Improved interface for settings in the MPC, MHE, Simulator, etc.
All do-mpc core modules now have the important new attribute ``settings``.
Previously, settings were passed to ``set_param``. This method is still available and wraps the new interface. The new method has important advantages:
1. The ``settings`` attribute can be printed to see the current configuration.
2. Context help is available in most IDEs (e.g. VS Code) to see the available settings, the type and a description.

#### Relaunch of documentation
We have significantly improved our documentation with a polished new look and included typing information for an improved workflow. 
## v4.5.1
Please see the changes for v.4.5.0. This is a minor update to fix the installation routine of do-mpc.
## v4.5.0
### Major changes

#### Linear control
- Newly implemented class ``LinearModel``. The linear model can be created by:
    - linearizing a regular (nonlinear) ``Model`` instance
    - passing system matrices ``(A,B,C,D)``
    - creating (linear) equations in ``LinearModel`` with the well known syntax used in ``Model``.
- Discretize a (continuous-time) ``LinearModel``.
- Setup the new discrete-time linear quadratic regulator (``LQR``) controller class

#### Data-based system identification with neural networks
- Use neural networks as system models in do-mpc
    - ``ONNXConversion`` can convert a previously trained and stored neural network to a CasADi graph
    - ONNX files can be exported from most major neural network frameworks (e.g. tensorflow, pytorch, matlab, ...)
    - Some limitations to the neural network operations apply.

### Minor changes

#### Compile NLP
- The ``MHE``, ``MPC`` classes can now export and compile the NLP. 
- Compiled NLPs can be loaded and solved. This may result in faster optimization times. 

#### Improved sampling tools for data generation
- Optional parameters in ``__init__`` of ``Sampler``, ``SamplingPlanner``, ``DataHandler`` that are passed to ``set_param``. This allows for a more concise setup.
- ``SamplingPlanner`` method ``product`` to create cartesian product (grid) of input variables to create test cases.

#### Simulator
- ``Simulator.make_step()`` can now be called without control input for autonomous systems.

### Bug fixes
- Example files now import do-mpc relative path with ``os.path.join`` to yield a OS agnostic implementation.
- ``MHE`` class can now be created without estimating parameters. 
- Solves visualization bug described in #340 

### Backend
- Significant code refactoring 
    - Many modules (e.g. ``controller.py``) were getting to large
    - Individual files (e.g. ``_mpc.py``) in subfolder ``do_mpc/controller/`` for large classes
    - User-facing classes (e.g. ``MPC``) imported in ``do_mpc/controller/__init__.py``.
        - Imported such that ``do_mpc.controller.MPC`` still yields the ``MPC`` class 
        - No changes in front-end for users
    - Recursive documentation with Sphinx / Readthedocs is fully automated now. Important considerations:
        - Private files (marked as e.g. ``_mpc.py``) are not documented
        - Imported modules are documented (e.g. the imported ``MPC`` class.
        - Importing with ``from casadi import *`` could result in documentation of CasADi package in **do-mpc**. This is avoided by:
            - Explicitly excluding certain packages (e.g. ``casadi``) to be documented.
            - Marking functions or classes as private with ``_Name``.
            - Using the ``__all__ = [...]`` variable to mark in certain files the list of elements that should be documented.

## v4.4.0
### Major changes
- MHE/MPC bounds on optimiziation variables can now be changed after calling ``mhe.setup()`` and ``mpc.setup()`` respectively (fixes #289). The simplest way to set bounds is the ``mhe.bounds`` and ``mpc.bounds`` property ([docs](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.bounds.html))
- More granular control over the bounds is now possible, e.g. choosing different values for each time-step of the horizon or for different collocation points (if that makes sense). For this purpose two now properties ``lb_opt_x`` and ``ub_opt_x`` are now documented and accessible to the user. These properties are indexed similarly to the property [opt_x](https://www.do-mpc.com/en/latest/api/do_mpc.controller.MPC.opt_x.html). Importantly, setting new values on these structure automatically considers the scaling factors.
- The do-mpc model can now be pickled. Pickling is restricted, however and requires (error messages are thrown otherwise):
    - the model class must be setup
    - the model must use ``SX`` symbolic variables
- Enhanced warmstarting: The solver is now supplied with a guess for the dual variables

### Minor changes 
- Bug fix: [MPCData.prediction](https://www.do-mpc.com/en/latest/api/do_mpc.data.MPCData.prediction.html) was previously unable to query algebraic states ``_z``.
- Fixed #283: Algebraic states can now be plotted with the graphics package
## v4.3.5
### Minor fixes 
- Setup for release in v4.3.4 was incomplete. 
## v4.3.4
### Minor fixes

- ``model.aux`` can now be queried before calling ``model.setup()``
- Some typos in documentation
## v4.3.3
### Major changes

- ``DataHandler`` class can now create ``post_processing_function`` considering inputs from the case-definition as created in the ``SamplingPlanner``.

### Minor changes

- All cost terms that are continuously appended to are now initialised with value ``DM(0)``. If nothing is appended (i.e. the term is not active), this avoids unclear error messages. This should fix #214 and #86

### Documentation

Minor fixes.
### Example files
Please download the example files for release v4.3.3 [here](https://github.com/do-mpc/do-mpc/releases/download/v4.3.3/examples.zip).
## v4.3.2.
### Major fixes

- Solved #215 
- Hoping to solve #233  
## v4.3.1
Fixed an issue with release 4.3.0 where sampling tools where not included on pypi.
## v4.3.0
### 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

### Example files
Please download the example files for release v4.3.0 [here](https://github.com/do-mpc/do-mpc/releases/download/v4.3.0/examples.zip).
## v4.2.5
### 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)
```
## v4.2.0
### 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.
## v4.1.1
### 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.

## do-mpc v4.1.0
### 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 
### Example files
Please download the example files for release do-mpc v4.1.0 [here](https://github.com/do-mpc/do-mpc/releases/download/v4.1.0/examples.zip).
## do-mpc v4.0.0
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:
![image](https://user-images.githubusercontent.com/32864011/84062539-be9c8d80-a9bf-11ea-9909-0e2d4e684f72.png)
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.
### Example files
Please download the example files for release do-mpc v4.0.0 [here](https://github.com/do-mpc/do-mpc/releases/download/v4.0.0/examples.zip).
## do-mpc v4.0.0-beta3
### 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)
### Example files
Please download the example files for release do-mpc v4.0.0-beta3 [here](https://github.com/do-mpc/do-mpc/releases/download/v4.0.0-beta3/examples.zip).
## do-mpc v4.0.0-beta2
Error in release. Immediately replaced with beta3.
## do-mpc v4.0.0-beta1
### 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
### Example files
Please download the example files for release do-mpc v4.0.0-beta1 [here](https://github.com/do-mpc/do-mpc/releases/download/v4.0.0-beta1/examples.zip).
## do-mpc v4.0.0-beta
**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.
### Example files
Please download the example files for release do-mpc v4.0.0-beta [here](https://github.com/do-mpc/do-mpc/releases/download/v4.0.0-beta/examples.zip).
## do-mpc v3.0.0
### Main modifications

- Support for CasADi version 3.4.4
- Support for time-varying parameters
- Support for discrete-time systems
## do-mpc v2.0.0
Compatible with CasADi 3.0.0

## do-mpc version 1.0.0