add docs for input-output handling (#2918)

* add docs for input-output handling

addresses #2852

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/Linearization.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/Linearization.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/InputOutput.md

* Update docs/src/basics/InputOutput.md

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/Linearization.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/Linearization.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/src/basics/InputOutput.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

---------

Co-authored-by: Christopher Rackauckas <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

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",

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
+```

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

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
 
 ```