Tutorial.md improved

Author: MartinOtter

docs/src/Tutorial.md

@@ -19,11 +19,10 @@ voltage source is modelled with an inner resistor):
 
 ### 1.1 Bi-Partite Graph
 
-After simple equations have been removed, this circuit can be
-described with 6 equations. The structure of the equations is
-displayed in the next figure:
+In a first step, the structural information of the low pass filter model is provided as incidence matrix
+
+![Incidence Matrix of Low Pass Filter](../resources/images/LowPassFilter_IncidenceMatrix.png)
 
-![Incidence Matrix of Low Pass Filter](../resources/images/LowPassFilterReduced_IncidenceMatrix.png)
 
 - Every **column** corresponds to one time-varying **variable**.
   Parameters, so variables with constant values, are not shown.
@@ -37,36 +36,92 @@ displayed in the next figure:
 
 The matrix above is called the **incidence matrix** or the
 **bi-partite graph** of the circuit. In ModiaBase, this matrix is represented
-as vector `G` of integer vectors:
+as vector `G` of Integer vectors:
 
 ```julia
 # Bi-partite graph of low pass filter
-G = [ [1,2,4],  # equation 1 depends on variables 1,2,4
-      [1,7],
-      [3,4],
-      [3,7],
-      [6,7],
-      [2] ]
+G = [ [25,27],  # equation 1 depends on variables 25,27
+      [6,23],
+      [4,10],
+      ...,
+      [27] ]
 ```
 
-This can be also made more explicit (and a bit more efficient storage
-by defining the incidence matrix as):
-
+This can be also made more explicit (and a bit more efficient storage)
+by defining the incidence matrix as:
 
 ```julia
 # Bi-partite graph of low pass filter
+G = Vector{Int}[ [25,27],  # equation 1 depends on variables 25,27
+                 [6,23],
+                 [4,10],
+                 ...,
+                 [27] ]
+```
+
+### 1.2 Linear Integer Equations
+
+Object-oriented models consist of a lot of linear Integer equations, especially due to the connect-statements.
+The linear integer equations of `G` are identified and the corresponding linear factors
+are determined. With function [`simplifyLinearIntegerEquations!`](@ref) this information is used to simplify
+the equations by transforming the linear Integer equations with a fraction-free (exact) Gaussian elimination to
+a special normalized form and then perform the following simplifications:
+
+- Equations of the form `v = 0` are removed and `v` is replaced by „0“ at all places where
+  `v` occurs, and these equations are simplified.
+
+- Equations of the form `v1 = v2` and `v1 = -v2` are removed, `v1`  is replaced by `v2` (or `-v2`)
+  at all places where `v1` occurs (so called *alias-variables*), and these equations are simplified.
+
+- *Redundant equations* are removed.
+
+- Variables that appear *only* in the linear Integer equations (and in no other equations) are set to zero, if
+  they can be *arbitrarily selected*. For example, if an electrical circuit is not
+  grounded, then one of the electrical potentials is arbitrarily set to zero.
+
+- State constraints are made structurally visible.
+
+After applying [`simplifyLinearIntegerEquations!`](@ref) to the low pass filter circuit,
+the incidence matrix is simplified to
+
+![Incidence Matrix of Low Pass Filter](../resources/images/LowPassFilterReduced_IncidenceMatrix.png)
+
+```julia
+# Bi-partite graph of simplified low pass filter
 G = Vector{Int}[ [1,2,4],
                  [1,7],
                  [3,4],
                  [3,7],
                  [6,7],
                  [2] ]
+
+# Eliminated variables
+R.i        = -(V.p.i)
+ground.p.v = 0
+R.p.i      = -(V.p.i)
+R.n.v      = C.v
+V.n.i      = -(V.p.i)
+V.n.v      = 0
+V.p.v      = Ri.n.v
+Ri.p.i     = V.p.i
+C.n.v      = 0
+C.p.v      = C.v
+Ri.p.v     = R.p.v
+C.n.i      = V.p.i
+V.i        = V.p.i
+R.n.i      = V.p.i
+C.p.i      = -(V.p.i)
+ground.p.i = 0
+C.i        = -(V.p.i)
+Ri.i       = V.p.i
+V.v        = Ri.n.v
+Ri.n.i     = -(V.p.i)
 ```
 
 
-### 1.2 Assignment
+### 1.3 Assignment
 
-In a first step, an assignment is made (also called matching), to associate
+In a follow-up step, an assignment is made (also called matching), to associate
 one variable uniquely with one equation:
 
 ![Matched IIncidence Matrix of Low Pass Filter](../resources/images/LowPassFilterReduced_Matching.png)
@@ -75,7 +130,7 @@ one variable uniquely with one equation:
 - *Blue* marks show if a variable is part of the respective equation
 
 The assignment is computed with function [`ModiaBase.matching`](@ref)
-returning a vector **assign**:
+returning a vector `assign`:
 
 ```julia
 using ModiaBase
@@ -94,9 +149,9 @@ The meaning of vector `assign` is that
 - etc.
 
 
-### 1.3 Block Lower Triangular transformation
+### 1.4 Block Lower Triangular transformation
 
-In a second step, equations are sorted and algebraic loops determined:
+In a follow-up step, equations are sorted and algebraic loops determined:
 
 ![Incidence Matrix of sorted equations of Low Pass Filter](../resources/images/LowPassFilterReduced_BLT.png)
 
@@ -112,8 +167,8 @@ blt = BLT(G, assign)
 
 #=
     blt = [ [6],
-           [3,4,2,1],
-           [5] ]
+            [3,4,2,1],
+            [5] ]
 =#
 ```