|
| 1 | +# [Input output](@id inputoutput) |
| 2 | + |
| 3 | +An input-output system is a system on the form |
| 4 | + |
| 5 | +```math |
| 6 | +\begin{aligned} |
| 7 | +M \dot x &= f(x, u, p, t) \\ |
| 8 | +y &= g(x, u, p, t) |
| 9 | +``` |
| 10 | + |
| 11 | +where ``x`` is the state, ``u`` is the input and ``y`` is an output (in some contexts called an _observed variables_ in MTK). |
| 12 | + |
| 13 | +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 |
| 14 | + |
| 15 | + - Linearization |
| 16 | + - Control design |
| 17 | + - System identification |
| 18 | + - FMU export |
| 19 | + - Real-time simulation with external data inputs |
| 20 | + - Custom interfacing with other simulation tools |
| 21 | + |
| 22 | +This documentation page lists utilities that are useful for working with inputs and outputs in ModelingToolkit. |
| 23 | + |
| 24 | +## Generating a dynamics function with inputs, ``f`` |
| 25 | + |
| 26 | +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. |
| 27 | + |
| 28 | +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``. |
| 29 | + |
| 30 | +!!! note "Un-simplified system" |
| 31 | + |
| 32 | + 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. |
| 33 | + |
| 34 | +## Generating an output function, ``g`` |
| 35 | + |
| 36 | +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. |
| 37 | + |
| 38 | +The order of the user-specified output variables determines the order of the output vector ``y``. |
| 39 | + |
| 40 | +## Input-output variable metadata |
| 41 | + |
| 42 | +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. |
| 43 | + |
| 44 | +## Linearization |
| 45 | + |
| 46 | +See [Linearization](@ref linearization). |
| 47 | + |
| 48 | +## Docstrings |
| 49 | + |
| 50 | +```@index |
| 51 | +Pages = ["InputOutput.md"] |
| 52 | +``` |
| 53 | + |
| 54 | +```@docs |
| 55 | +ModelingToolkit.generate_control_function |
| 56 | +ModelingToolkit.build_explicit_observed_function |
| 57 | +``` |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments