From 51afdc138b9d512098c84871aa60d3fbfd96db40 Mon Sep 17 00:00:00 2001 From: Fredrik Bagge Carlson Date: Thu, 8 Aug 2024 07:05:00 +0200 Subject: [PATCH 1/7] add an example to IO docs --- docs/src/basics/InputOutput.md | 44 ++++++++++++++++++++++++++++++++-- src/inputoutput.jl | 8 +++---- 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 5c0a99c06c..347da8929c 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -24,14 +24,54 @@ 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. + +```@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. diff --git a/src/inputoutput.jl b/src/inputoutput.jl index d9a1d8a1c2..03b5d3e0a1 100644 --- a/src/inputoutput.jl +++ b/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) ``` From 80b19c88b15c600b0b71a65ad79fb0e5a3d496c2 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Thu, 8 Aug 2024 08:16:10 -0400 Subject: [PATCH 2/7] Update docs/src/basics/InputOutput.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/InputOutput.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 347da8929c..84d8939ac7 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -54,6 +54,7 @@ We can inspect the state realization chosen by MTK x_sym ``` +as expected, `x` is chosen as the state variable. as expected, `x` is chosen as the state variable. ```@example inputoutput From 67d89da1daf13595b17e7dcfe5788b257dda6d94 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Thu, 8 Aug 2024 08:16:15 -0400 Subject: [PATCH 3/7] Update docs/src/basics/InputOutput.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/InputOutput.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 84d8939ac7..96b10a01fb 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -66,6 +66,7 @@ nothing # hide Now we can test the generated function `f` with random input and state values + ```@example inputoutput p = [1] x = [rand()] From 07a739394fface98a407bf50ba716900d5b4e536 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Thu, 8 Aug 2024 08:16:20 -0400 Subject: [PATCH 4/7] Update docs/src/basics/InputOutput.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/InputOutput.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 96b10a01fb..52b4015d7f 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -50,6 +50,7 @@ nothing # hide We can inspect the state realization chosen by MTK + ```@example inputoutput x_sym ``` From 5d037e840d6d7d67d9756b0d0d6f570af93f4c5b Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Thu, 8 Aug 2024 08:16:24 -0400 Subject: [PATCH 5/7] Update docs/src/basics/InputOutput.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/InputOutput.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 52b4015d7f..b8cd75a6d8 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -48,6 +48,7 @@ f, x_sym, ps = ModelingToolkit.generate_control_function(sys, [u], simplify = tr nothing # hide ``` + We can inspect the state realization chosen by MTK From 2cc5cad9d34c21c6a56184e0db57c08baf089aaf Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Thu, 8 Aug 2024 08:16:28 -0400 Subject: [PATCH 6/7] Update docs/src/basics/InputOutput.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/InputOutput.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index b8cd75a6d8..92a3022f6b 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -36,6 +36,7 @@ This function takes a vector of variables that are to be considered inputs, i.e. 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) From 01c03cd922ff82735fa47e62016cb38adadf4de3 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Thu, 8 Aug 2024 08:16:33 -0400 Subject: [PATCH 7/7] Update docs/src/basics/InputOutput.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/InputOutput.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 92a3022f6b..09bf47331a 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -34,6 +34,7 @@ This function takes a vector of variables that are to be considered inputs, i.e. ### 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.