From cfcfaa34278a1c8eebb8ac3c2c4dec819e4d940c Mon Sep 17 00:00:00 2001 From: Fredrik Bagge Carlson Date: Fri, 2 Aug 2024 10:34:36 +0200 Subject: [PATCH 01/15] add docs for input-output handling addresses #2852 --- docs/pages.jl | 1 + docs/src/basics/InputOutput.md | 57 ++++++++++++++++++++++++++++++++ docs/src/basics/Linearization.md | 12 ++++++- src/inputoutput.jl | 3 ++ 4 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 docs/src/basics/InputOutput.md diff --git a/docs/pages.jl b/docs/pages.jl index a58d1dcf1a..f92f869def 100644 --- a/docs/pages.jl +++ b/docs/pages.jl @@ -28,6 +28,7 @@ pages = [ "basics/Composition.md", "basics/Events.md", "basics/Linearization.md", + "basics/InputOutput.md", "basics/MTKLanguage.md", "basics/Validation.md", "basics/DependencyGraphs.md", diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md new file mode 100644 index 0000000000..99e2fab0e1 --- /dev/null +++ b/docs/src/basics/InputOutput.md @@ -0,0 +1,57 @@ +# [Input output](@id inputoutput) + +An input-output system is a system on the form + +```math +\begin{aligned} +M \dot x &= f(x, u, p, t) \\ +y &= g(x, u, p, t) +``` + +where ``x`` is the state, ``u`` is the input and ``y`` is an output (in some contexts called an _observed variables_ in MTK). + +While many uses of ModelingToolkit for simulation do not require the user to think about inputs and outputs (IO), there are certain situations in which handling IO explicitly may be important, such as + + - Linearization + - Control design + - System identification + - FMU export + - Real-time simulation with external data inputs + - Custom interfacing with other simulation tools + +This documentation page lists utilities that are useful for working with inputs and outputs in ModelingToolkit. + +## 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. + +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``. + +!!! 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. + +## 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. + +The order of the user-specified output variables determines the order of the output vector ``y``. + +## Input-output variable metadata + +See [Symbolic Metadata](@ref symbolic_metadata). Metadata specified when creating variables is not directly used by any of the functions above, but the user can use the accessor functions `ModelingToolkit.inputs(sys)` and `ModelingToolkit.outputs(sys)` to obtain all variables with such metadata for passing to the functions above. The presence of this metadata is not required for any IO functionality and may be omitted. + +## Linearization + +See [Linearization](@ref linearization). + +## Docstrings + +```@index +Pages = ["InputOutput.md"] +``` + +```@docs +ModelingToolkit.generate_control_function +ModelingToolkit.build_explicit_observed_function +``` diff --git a/docs/src/basics/Linearization.md b/docs/src/basics/Linearization.md index 5a215b728f..ab76facec1 100644 --- a/docs/src/basics/Linearization.md +++ b/docs/src/basics/Linearization.md @@ -29,7 +29,7 @@ eqs = [u ~ kp * (r - y) # P controller D(x) ~ -x + u # First-order plant y ~ x] # Output equation -@named sys = ODESystem(eqs, t) +@named sys = ODESystem(eqs, t) # Do not call @mtkbuild when linearizing matrices, simplified_sys = linearize(sys, [r], [y]) # Linearize from r to y matrices ``` @@ -41,6 +41,14 @@ using ModelingToolkit: inputs, outputs [unknowns(simplified_sys); inputs(simplified_sys); outputs(simplified_sys)] ``` +!!! note "Inputs must be unconnected" + + The model above has 4 variables but only three equations, there is no equation specifying the value of `r` since `r` is an input. This means that only unbalanced models can be linearized, or in other words, models that are balanced and can be simulated _cannot_ be linearized. To learn more about this, see https://www.youtube.com/watch?v=-XOux-2XDGI&t=395s. Also see [ModelingToolkitStandardLibrary: Linear analysis](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/linear_analysis/) for utilities that make linearization of completed models easier. + +!!! note "Un-simplified system" + + Linearization expects `sys` to be un-simplified, i.e., `structural_simplify` or `@mtkbuild` should not be called on the system before linearizing. + ## Operating point The operating point to linearize around can be specified with the keyword argument `op` like this: `op = Dict(x => 1, r => 2)`. The operating point may include specification of unknown variables, input variables and parameters. For variables that are not specified in `op`, the default value specified in the model will be used if available, if no value is specified, an error is thrown. @@ -69,6 +77,8 @@ If the modeled system is actually proper (but MTK failed to find a proper realiz [ModelingToolkitStandardLibrary](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/) contains a set of [tools for more advanced linear analysis](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/linear_analysis/). These can be used to make it easier to work with and analyze causal models, such as control and signal-processing systems. +Also see [ControlSystemsMTK.jl](https://juliacontrol.github.io/ControlSystemsMTK.jl/dev/) for an interface to [ControlSystems.jl](https://github.com/JuliaControl/ControlSystems.jl) that contains tools for linear analysis and frequency-domain analysis. + ## Docstrings ```@index diff --git a/src/inputoutput.jl b/src/inputoutput.jl index 6ef36cddcc..d20b110967 100644 --- a/src/inputoutput.jl +++ b/src/inputoutput.jl @@ -180,6 +180,9 @@ The return values also include the remaining unknowns and parameters, in the ord 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. +!!! 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 ``` From b2fc08d6304967d83ad85c2984b2fee8806b219b Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:31:05 -0400 Subject: [PATCH 02/15] 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 99e2fab0e1..930c1fbeca 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -29,6 +29,7 @@ This function takes a vector of variables that are to be considered inputs, i.e. !!! 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. ## Generating an output function, ``g`` From 36f1cf988e146222fca542292e6e8c92212b7877 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:31:10 -0400 Subject: [PATCH 03/15] 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 930c1fbeca..0bf44bc617 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -23,6 +23,7 @@ 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. 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``. From e3ae95343b8de0494864caf21378529e910c271d Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:31:15 -0400 Subject: [PATCH 04/15] Update docs/src/basics/Linearization.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/Linearization.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/Linearization.md b/docs/src/basics/Linearization.md index ab76facec1..395fa9bb5e 100644 --- a/docs/src/basics/Linearization.md +++ b/docs/src/basics/Linearization.md @@ -43,6 +43,7 @@ using ModelingToolkit: inputs, outputs !!! note "Inputs must be unconnected" + The model above has 4 variables but only three equations, there is no equation specifying the value of `r` since `r` is an input. This means that only unbalanced models can be linearized, or in other words, models that are balanced and can be simulated _cannot_ be linearized. To learn more about this, see https://www.youtube.com/watch?v=-XOux-2XDGI&t=395s. Also see [ModelingToolkitStandardLibrary: Linear analysis](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/linear_analysis/) for utilities that make linearization of completed models easier. !!! note "Un-simplified system" From d9e9fb180d2ad1d1b33ec58652202e976674a8a9 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:31:21 -0400 Subject: [PATCH 05/15] 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 0bf44bc617..c232b9a935 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -35,6 +35,7 @@ This function takes a vector of variables that are to be considered inputs, i.e. ## 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. The order of the user-specified output variables determines the order of the output vector ``y``. From fcb78f8d2030edcb0c0f3920d6d7ee977b7f9b35 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:31:27 -0400 Subject: [PATCH 06/15] 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 c232b9a935..d68bb02460 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -43,6 +43,7 @@ The order of the user-specified output variables determines the order of the out ## Input-output variable metadata See [Symbolic Metadata](@ref symbolic_metadata). Metadata specified when creating variables is not directly used by any of the functions above, but the user can use the accessor functions `ModelingToolkit.inputs(sys)` and `ModelingToolkit.outputs(sys)` to obtain all variables with such metadata for passing to the functions above. The presence of this metadata is not required for any IO functionality and may be omitted. +See [Symbolic Metadata](@id symbolic_metadata). Metadata specified when creating variables is not directly used by any of the functions above, but the user can use the accessor functions `ModelingToolkit.inputs(sys)` and `ModelingToolkit.outputs(sys)` to obtain all variables with such metadata for passing to the functions above. The presence of this metadata is not required for any IO functionality and may be omitted. ## Linearization From 34a377f45b6e13e04c76afd28ab188777a4a4a35 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:31:34 -0400 Subject: [PATCH 07/15] 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 d68bb02460..61a5aacd03 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -47,6 +47,7 @@ See [Symbolic Metadata](@id symbolic_metadata). Metadata specified when creating ## Linearization +See [Linearization](@ref linearization). See [Linearization](@ref linearization). ## Docstrings From 2047f0362a485a4bba2dbfed9cf6572de47d7f40 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:31:39 -0400 Subject: [PATCH 08/15] Update docs/src/basics/Linearization.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/Linearization.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/basics/Linearization.md b/docs/src/basics/Linearization.md index 395fa9bb5e..1fc3825697 100644 --- a/docs/src/basics/Linearization.md +++ b/docs/src/basics/Linearization.md @@ -48,6 +48,7 @@ using ModelingToolkit: inputs, outputs !!! note "Un-simplified system" + Linearization expects `sys` to be un-simplified, i.e., `structural_simplify` or `@mtkbuild` should not be called on the system before linearizing. ## Operating point From a79c20c142d8f3d040132b3dee52c6ba560d2ebc Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:32:29 -0400 Subject: [PATCH 09/15] Update docs/src/basics/InputOutput.md --- docs/src/basics/InputOutput.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 61a5aacd03..d68bb02460 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -47,7 +47,6 @@ See [Symbolic Metadata](@id symbolic_metadata). Metadata specified when creating ## Linearization -See [Linearization](@ref linearization). See [Linearization](@ref linearization). ## Docstrings From b3152fc17ab1377255022b6e29ace98c5322d123 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:33:00 -0400 Subject: [PATCH 10/15] Update docs/src/basics/InputOutput.md --- docs/src/basics/InputOutput.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index d68bb02460..c232b9a935 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -43,7 +43,6 @@ The order of the user-specified output variables determines the order of the out ## Input-output variable metadata See [Symbolic Metadata](@ref symbolic_metadata). Metadata specified when creating variables is not directly used by any of the functions above, but the user can use the accessor functions `ModelingToolkit.inputs(sys)` and `ModelingToolkit.outputs(sys)` to obtain all variables with such metadata for passing to the functions above. The presence of this metadata is not required for any IO functionality and may be omitted. -See [Symbolic Metadata](@id symbolic_metadata). Metadata specified when creating variables is not directly used by any of the functions above, but the user can use the accessor functions `ModelingToolkit.inputs(sys)` and `ModelingToolkit.outputs(sys)` to obtain all variables with such metadata for passing to the functions above. The presence of this metadata is not required for any IO functionality and may be omitted. ## Linearization From 6cb7c76154dd80634a35a27fae8f48846ff75406 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:34:50 -0400 Subject: [PATCH 11/15] 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 deletion(-) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index c232b9a935..f77cad6286 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -23,7 +23,6 @@ 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. 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``. From fdca1628c4b5385e92435d62a102f196c1cfefaa Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:34:55 -0400 Subject: [PATCH 12/15] Update docs/src/basics/Linearization.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/Linearization.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/src/basics/Linearization.md b/docs/src/basics/Linearization.md index 1fc3825697..395fa9bb5e 100644 --- a/docs/src/basics/Linearization.md +++ b/docs/src/basics/Linearization.md @@ -48,7 +48,6 @@ using ModelingToolkit: inputs, outputs !!! note "Un-simplified system" - Linearization expects `sys` to be un-simplified, i.e., `structural_simplify` or `@mtkbuild` should not be called on the system before linearizing. ## Operating point From 9acb0e0921f1afab6e8d43c2671962db07464d70 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:35:00 -0400 Subject: [PATCH 13/15] 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 deletion(-) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index f77cad6286..930c1fbeca 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -34,7 +34,6 @@ This function takes a vector of variables that are to be considered inputs, i.e. ## 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. The order of the user-specified output variables determines the order of the output vector ``y``. From 33efba8726662075ff75de936b09b394191249f7 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:35:04 -0400 Subject: [PATCH 14/15] Update docs/src/basics/Linearization.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/src/basics/Linearization.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/src/basics/Linearization.md b/docs/src/basics/Linearization.md index 395fa9bb5e..ab76facec1 100644 --- a/docs/src/basics/Linearization.md +++ b/docs/src/basics/Linearization.md @@ -43,7 +43,6 @@ using ModelingToolkit: inputs, outputs !!! note "Inputs must be unconnected" - The model above has 4 variables but only three equations, there is no equation specifying the value of `r` since `r` is an input. This means that only unbalanced models can be linearized, or in other words, models that are balanced and can be simulated _cannot_ be linearized. To learn more about this, see https://www.youtube.com/watch?v=-XOux-2XDGI&t=395s. Also see [ModelingToolkitStandardLibrary: Linear analysis](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/linear_analysis/) for utilities that make linearization of completed models easier. !!! note "Un-simplified system" From 8085d76e924704a4d7a450dd4eeea048965aeb48 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Fri, 2 Aug 2024 08:35:08 -0400 Subject: [PATCH 15/15] 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 deletion(-) diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md index 930c1fbeca..99e2fab0e1 100644 --- a/docs/src/basics/InputOutput.md +++ b/docs/src/basics/InputOutput.md @@ -29,7 +29,6 @@ This function takes a vector of variables that are to be considered inputs, i.e. !!! 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. ## Generating an output function, ``g``