doc: info on mutating NonLinModel

Author: franckgaga

docs/src/internals/sim_model.md

@@ -7,8 +7,8 @@ Pages = ["sim_model.md"]
 ## State-Space Functions
 
 ```@docs
-ModelPredictiveControl.f
-ModelPredictiveControl.h
+ModelPredictiveControl.f!
+ModelPredictiveControl.h!
 ```
 
 ## Steady-State Calculation

docs/src/internals/state_estim.md

@@ -7,8 +7,8 @@ Pages = ["state_estim.md"]
 ## Augmented Model
 
 ```@docs
-ModelPredictiveControl.f̂
-ModelPredictiveControl.ĥ
+ModelPredictiveControl.f̂!
+ModelPredictiveControl.ĥ!
 ```
 
 ## Constraint Relaxation

src/model/nonlinmodel.jl

@@ -23,7 +23,7 @@ struct NonLinModel{NT<:Real, F<:Function, H<:Function} <: SimModel{NT}
 end
 
 @doc raw"""
-    NonLinModel{NT}( f::Function,  h::Function, Ts, nu, nx, ny, nd=0)
+    NonLinModel{NT}(f::Function,  h::Function,  Ts, nu, nx, ny, nd=0)
     NonLinModel{NT}(f!::Function, h!::Function, Ts, nu, nx, ny, nd=0)
 
 Construct a nonlinear model from discrete-time state-space functions `f` and `h`.
@@ -35,14 +35,14 @@ The state update ``\mathbf{f}`` and output ``\mathbf{h}`` functions are defined
     \mathbf{y}(k)   &= \mathbf{h}\Big( \mathbf{x}(k), \mathbf{d}(k) \Big)
     \end{aligned}
 ```
-They can be specified in two forms:
+They can be implemented in two possible ways:
 
 - non-mutating functions (out-of-place): they must be defined as `f(x, u, d) -> xnext` and
-  `h(x, d) -> y`
+  `h(x, d) -> y`. This syntax is simple and intuitive but it allocates more memory.
 - mutating functions (in-place): they must be defined as `f!(xnext, x, u, d) -> nothing` and
   `h!(y, x, d) -> nothing`. This syntax reduces the allocations and potentially the 
   computational burden as well.
-  
+
 `Ts` is the sampling time in second. `nu`, `nx`, `ny` and `nd` are the respective number of 
 manipulated inputs, states, outputs and measured disturbances. The optional parameter `NT`
 explicitly specifies the number type of vectors (default to `Float64`).
@@ -51,17 +51,28 @@ explicitly specifies the number type of vectors (default to `Float64`).
     Replace the `d` argument with `_` if `nd = 0` (see Examples below).
 
 Nonlinear continuous-time state-space functions are not supported for now. In such a case, 
-manually call a differential equation solver in `f` (see [Manual](@ref man_nonlin)).
+manually call a differential equation solver in `f` / `f!` (see [Manual](@ref man_nonlin)).
 
 !!! warning
-    `f` and `h` must be pure Julia functions to use the model in [`NonLinMPC`](@ref),
+    The two functions must be in pure Julia to use the model in [`NonLinMPC`](@ref),
     [`ExtendedKalmanFilter`](@ref), [`MovingHorizonEstimator`](@ref) and [`linearize`](@ref).
 
 See also [`LinModel`](@ref).
 
 # Examples
 ```jldoctest
-julia> model = NonLinModel((x,u,_)->0.1x+u, (x,_)->2x, 10.0, 1, 1, 1)
+julia> model1 = NonLinModel((x,u,_)->0.1x+u, (x,_)->2x, 10.0, 1, 1, 1)
+Discrete-time nonlinear model with a sample time Ts = 10.0 s and:
+ 1 manipulated inputs u
+ 1 states x
+ 1 outputs y
+ 0 measured disturbances d
+
+julia> f!(xnext,x,u,_) = (xnext .= 0.1x .+ u; nothing);
+
+julia> h!(y,x,_) = (y .= 2x; nothing);
+
+julia> model2 = NonLinModel(f!, h!, 10.0, 1, 1, 1) 
 Discrete-time nonlinear model with a sample time Ts = 10.0 s and:
  1 manipulated inputs u
  1 states x