document state order

Author: baggepinnen

docs/src/examples/ilc.md

@@ -1,5 +1,5 @@
 # Iterative-Learning Control
-In this example, we will design an [Iterative-Learning Control (ILC)](https://en.wikipedia.org/wiki/Iterative_learning_control) iteration scheme. ILC can be though of as a simple reinforcement-learning strategy that is suitable in situations where a *repetitive task* is to be performed multiple times, and disturbances acting on the system are also repetitive and predictable but unknown. Multiple versions of ILC exists, in this tutorial we will consider a heuristic scheme as well as a model-based scheme. 
+In this example, we will design an [Iterative-Learning Control (ILC)](https://en.wikipedia.org/wiki/Iterative_learning_control) iteration scheme. ILC can be thought of as a simple reinforcement-learning strategy that is suitable in situations where a *repetitive task* is to be performed multiple times, and disturbances acting on the system are also repetitive and predictable but unknown. Multiple versions of ILC exists, in this tutorial we will consider a heuristic scheme as well as a model-based scheme. 
 
 ## Algorithm
 
@@ -102,7 +102,7 @@ nothing # hide
 ```
 
 ## Choosing filters
-The next step is to define the ILC filters ``Q(x)`` and ``L(z)``.
+The next step is to define the ILC filters ``Q(q)`` and ``L(q)``.
 
 The filter $L(q)$ acts as a frequency-dependent step size. To make the procedure take smaller steps, simply scale $L$ by a constant < 1. Scaling down $L$ makes the learning process slower but more robust. A heuristic choice of $L$ is some form of scaled lookahead, such as $0.5z^l$ where $l \geq 0$ is the number of samples lookahead. A model-based approach may use some form of inverse of the system model, which is what we will use here. [^nonlinear]
 

docs/src/lib/nonlinear.md

@@ -113,7 +113,7 @@ yr    = G.C*xr  # Reference output
 Gop   = offset(yr) * G * offset(-ur) # Make the plant operate in Δ-coordinates 
 C_sat = saturation(umin, umax) * C   # while the controller and the saturation operate in the original coordinates
 ```
-We now simulate the closed-loop system, the initial state of the plant is adjusted with the operating point `x0-xr` since the plant operates in Δ-coordinates 
+We now simulate the closed-loop system, the initial state of the plant is adjusted with the operating point `x0-xr` since the plant operates in Δ-coordinates
 ```@example nonlinear
 x0 = [2, 1, 8, 3] # Initial tank levels
 plot(
@@ -123,6 +123,8 @@ plot(
 hline!([yr[1]], label="Reference", l=:dash, sp=1, c=1)
 ```
 
+The state vector resulting from the call to `feedback` is comprised of the concatenated states of the first and second arguments, i.e., `feedback(C_sat, Gop)` has the state vector `[C_sat.x; Gop.x]` while `feedback(Gop*C_sat)` has the state vector of `Gop*C_sat` which is starting with the first operand, `[Gop.x; C_sat.x]`.
+
 
 ### Duffing oscillator
 In this example, we'll model and control the nonlinear system

docs/src/man/creating_systems.md

@@ -180,6 +180,9 @@ P1 = ss(-1,1,1,0)
 P2 = ss(-2,1,1,0)
 P2*P1
 ```
+
+The state of the resulting system is the concatenation of the states of the two systems, starting with the left/first operand (`P2` above).
+
 If the input dimension of `P2` does not match the output dimension of `P1`, an error is thrown. If one of the systems is SISO and the other is MIMO, broadcasted multiplication will expand the SISO system to match the input or output dimension of the MIMO system, e.g.,
 ```@example MIMO
 Pmimo = ssrand(2,2,1)
@@ -194,6 +197,12 @@ using LinearAlgebra
 Psiso .* I(2)
 ```
 
+## Adding systems
+Two systems can be connected in parallel by addition
+```@example MIMO
+P12 = P1 + P2
+```
+The state of the resulting system is the concatenation of the states of the two systems, starting with the left/first operand (`P1` above).
 
 ## MIMO systems and arrays of systems
 Concatenation of systems creates MIMO systems, which is different from an array of systems. For example
@@ -267,6 +276,8 @@ This section lists a number of block diagrams, and indicates the corresponding t
 
 The function `feedback(G1, G2)` can be thought of like this: the first argument `G1` is the system that appears directly between the input and the output (the *forward path*), while the second argument `G2` (defaults to 1 if omitted) contains all other systems that appear in the closed loop (the *feedback path*). The feedback is assumed to be negative, unless the argument `pos_feedback = true` is passed (`lft` is an exception, which due to convention defaults to positive feedback). This means that `feedback(G, 1)` results in unit negative feedback, while `feedback(G, -1)` or `feedback(G, 1, pos_feedback = true)` results in unit positive feedback.
 
+The returned closed-loop system will have a state vector comprised of the state of `G1` followed by the state of `G2`.
+
 ---
 Closed-loop system from reference to output
 ```

lib/ControlSystemsBase/src/connections.jl

@@ -288,6 +288,7 @@ end
            └──────────────┘
 ```
 If no second system `sys2` is given, negative identity feedback (`sys2 = 1`) is assumed.
+The returned closed-loop system will have a state vector comprised of the state of `sys1` followed by the state of `sys2`.
 
 *Advanced use*
 `feedback` also supports more flexible use according to the figure below