Merge pull request #2926 from SciML/lin3

add an example to IO docs

Author: ChrisRackauckas

docs/src/basics/InputOutput.md

@@ -24,14 +24,60 @@ This documentation page lists utilities that are useful for working with inputs
 
 ## Generating a dynamics function with inputs, ``f``
 
-ModelingToolkit can generate the dynamics of a system, the function ``M\dot x = f(x, u, p, t)`` above, such that the user can pass not only the state ``x`` and parameters ``p`` but also an external input ``u``. To this end, the function [`generate_control_function`](@ref) exists.
+ModelingToolkit can generate the dynamics of a system, the function ``M\dot x = f(x, u, p, t)`` above, such that the user can pass not only the state ``x`` and parameters ``p`` but also an external input ``u``. To this end, the function [`ModelingToolkit.generate_control_function`](@ref) exists.
 
-This function takes a vector of variables that are to be considered inputs, i.e., part of the vector ``u``. Alongside returning the function ``f``, [`generate_control_function`](@ref) also returns the chosen state realization of the system after simplification. This vector specifies the order of the state variables ``x``, while the user-specified vector `u` specifies the order of the input variables ``u``.
+This function takes a vector of variables that are to be considered inputs, i.e., part of the vector ``u``. Alongside returning the function ``f``, [`ModelingToolkit.generate_control_function`](@ref) also returns the chosen state realization of the system after simplification. This vector specifies the order of the state variables ``x``, while the user-specified vector `u` specifies the order of the input variables ``u``.
 
 !!! note "Un-simplified system"
 
     This function expects `sys` to be un-simplified, i.e., `structural_simplify` or `@mtkbuild` should not be called on the system before passing it into this function. `generate_control_function` calls a special version of `structural_simplify` internally.
 
+### Example:
+
+
+The following example implements a simple first-order system with an input `u` and state `x`. The function `f` is generated using `generate_control_function`, and the function `f` is then tested with random input and state values.
+
+
+```@example inputoutput
+import ModelingToolkit: t_nounits as t, D_nounits as D
+@variables x(t)=0 u(t)=0 y(t)
+@parameters k = 1
+eqs = [D(x) ~ -k * (x + u)
+       y ~ x]
+
+@named sys = ODESystem(eqs, t)
+f, x_sym, ps = ModelingToolkit.generate_control_function(sys, [u], simplify = true);
+nothing # hide
+```
+
+
+We can inspect the state realization chosen by MTK
+
+
+```@example inputoutput
+x_sym
+```
+
+as expected, `x` is chosen as the state variable.
+as expected, `x` is chosen as the state variable.
+
+```@example inputoutput
+using Test # hide
+@test isequal(x_sym[], x) # hide
+@test isequal(ps, [k]) # hide
+nothing  # hide
+```
+
+Now we can test the generated function `f` with random input and state values
+
+
+```@example inputoutput
+p = [1]
+x = [rand()]
+u = [rand()]
+@test f[1](x, u, p, 1) ≈ -p[] * (x + u) # Test that the function computes what we expect D(x) = -k*(x + u)
+```
+
 ## Generating an output function, ``g``
 
 ModelingToolkit can also generate a function that computes a specified output of a system, the function ``y = g(x, u, p, t)`` above. This is done using the function [`build_explicit_observed_function`](@ref). When generating an output function, the user must specify the output variable(s) of interest, as well as any inputs if inputs are relevant to compute the output.

src/inputoutput.jl

@@ -160,7 +160,7 @@ has_var(ex, x) = x ∈ Set(get_variables(ex))
 # Build control function
 
 """
-    (f_oop, f_ip), dvs, p, io_sys = generate_control_function(
+    (f_oop, f_ip), x_sym, p, io_sys = generate_control_function(
             sys::AbstractODESystem,
             inputs             = unbound_inputs(sys),
             disturbance_inputs = nothing;
@@ -175,7 +175,7 @@ f_oop : (x,u,p,t)      -> rhs
 f_ip  : (xout,x,u,p,t) -> nothing
 ```
 
-The return values also include the remaining unknowns and parameters, in the order they appear as arguments to `f`.
+The return values also include the chosen state-realization (the remaining unknowns) `x_sym` and parameters, in the order they appear as arguments to `f`.
 
 If `disturbance_inputs` is an array of variables, the generated dynamics function will preserve any state and dynamics associated with disturbance inputs, but the disturbance inputs themselves will not be included as inputs to the generated function. The use case for this is to generate dynamics for state observers that estimate the influence of unmeasured disturbances, and thus require unknown variables for the disturbance model, but without disturbance inputs since the disturbances are not available for measurement.
 See [`add_input_disturbance`](@ref) for a higher-level interface to this functionality.
@@ -187,9 +187,9 @@ See [`add_input_disturbance`](@ref) for a higher-level interface to this functio
 
 ```
 using ModelingToolkit: generate_control_function, varmap_to_vars, defaults
-f, dvs, ps = generate_control_function(sys, expression=Val{false}, simplify=false)
+f, x_sym, ps = generate_control_function(sys, expression=Val{false}, simplify=false)
 p = varmap_to_vars(defaults(sys), ps)
-x = varmap_to_vars(defaults(sys), dvs)
+x = varmap_to_vars(defaults(sys), x_sym)
 t = 0
 f[1](x, inputs, p, t)
 ```