Refactors Electrical module with @mtkmodel (#192)

* refactor: refactor Electrical/Analog components with `@mtkmodel`

* docs: bump MTK to 8 (from 8.33) and fix custom_component example

Author: ven-k

docs/Project.toml

@@ -16,4 +16,4 @@ IfElse = "0.1"
 ModelingToolkit = "8"
 ModelingToolkitStandardLibrary = "1.8"
 OrdinaryDiffEq = "6.31"
-Plots = "1.36"
+Plots = "1.36"

docs/src/tutorials/custom_component.md

@@ -27,7 +27,7 @@ model NonlinearResistor "Chua's resistor"
   parameter SI.Conductance Ga "conductance in inner voltage range";
   parameter SI.Conductance Gb "conductance in outer voltage range";
   parameter SI.Voltage Ve "inner voltage range limit";
-equation 
+equation
   i = if (v < -Ve) then Gb*(v + Ve) - Ga*Ve else if (v > Ve) then Gb*(v - Ve) + Ga*Ve else Ga*v;
 end NonlinearResistor;
 ```
@@ -94,7 +94,7 @@ The final model can now be created with the components from the library and the
 @named L = Inductor(L = 18)
 @named Ro = Resistor(R = 12.5e-3)
 @named G = Conductor(G = 0.565)
-@named C1 = Capacitor(C = 10, v_start = 4)
+@named C1 = Capacitor(C = 10, v = 4)
 @named C2 = Capacitor(C = 100)
 @named Nr = NonlinearResistor(Ga = -0.757576,
     Gb = -0.409091,
@@ -119,7 +119,7 @@ nothing # hide
 
 Now the model can be simulated.
 First, `structural_simplify` is called on the model and an `ODEProblem` is built from the result.
-Since the initial voltage of the first capacitor was already specified via `v_start`, no initial condition is given and an empty pair is supplied.
+Since the initial voltage of the first capacitor was already specified via `v`, no initial condition is given and an empty pair is supplied.
 
 ```@example components
 sys = structural_simplify(model)

docs/src/tutorials/rc_circuit.md

@@ -16,7 +16,7 @@ C = 1.0
 V = 1.0
 @variables t
 @named resistor = Resistor(R = R)
-@named capacitor = Capacitor(C = C)
+@named capacitor = Capacitor(C = C, v = 0.0)
 @named source = Voltage()
 @named constant = Constant(k = V)
 @named ground = Ground()

src/Electrical/Analog/ideal_components.jl

@@ -8,10 +8,13 @@ node.
 
   - `g`
 """
-@component function Ground(; name)
-    @named g = Pin()
-    eqs = [g.v ~ 0]
-    ODESystem(eqs, t, [], []; systems = [g], name = name)
+@mtkmodel Ground begin
+    @components begin
+        g = Pin()
+    end
+    @equations begin
+        g.v ~ 0
+    end
 end
 
 """
@@ -32,18 +35,18 @@ See [OnePort](@ref)
 
   - `R`: [`Ohm`] Resistance
 """
-@component function Resistor(; name, R)
-    @named oneport = OnePort()
-    @unpack v, i = oneport
-    pars = @parameters R = R
-    eqs = [
-        v ~ i * R,
-    ]
-    extend(ODESystem(eqs, t, [], pars; name = name), oneport)
+@mtkmodel Resistor begin
+    @extend v, i = oneport = OnePort()
+    @parameters begin
+        R, [description = "Resistance"]
+    end
+    @equations begin
+        v ~ i * R
+    end
 end
 
 """
-    Conductor(;name, G)
+    Conductor(; name, G)
 
 Creates an ideal conductor.
 
@@ -60,24 +63,25 @@ See [OnePort](@ref)
 
   - `G`: [`S`] Conductance
 """
-@component function Conductor(; name, G)
-    @named oneport = OnePort()
-    @unpack v, i = oneport
-    pars = @parameters G = G
-    eqs = [
-        i ~ v * G,
-    ]
-    extend(ODESystem(eqs, t, [], pars; name = name), oneport)
+@mtkmodel Conductor begin
+    @extend v, i = oneport = OnePort()
+    @parameters begin
+        G, [description = "Conductance"]
+    end
+    @equations begin
+        i ~ v * G
+    end
 end
 
 """
-    Capacitor(; name, C)
+    Capacitor(; name, C, v)
 
 Creates an ideal capacitor.
+Initial voltage of capacitor can be set with `v` ([`V`])
 
 # States:
 
-  - `v(t)`: [`V`] The voltage across the capacitor, given by `D(v) ~ p.i / C`
+See [OnePort](@ref)
 
 # Connectors:
 
@@ -87,22 +91,25 @@ Creates an ideal capacitor.
 # Parameters:
 
   - `C`: [`F`] Capacitance
-  - `v_start`: [`V`] Initial voltage of capacitor
-"""
-@component function Capacitor(; name, C, v_start = 0.0)
-    @named oneport = OnePort(; v_start = v_start)
-    @unpack v, i = oneport
-    pars = @parameters C = C
-    eqs = [
-        D(v) ~ i / C,
-    ]
-    extend(ODESystem(eqs, t, [], pars; name = name), oneport)
+"""
+@mtkmodel Capacitor begin
+    @parameters begin
+        C, [description = "Capacitance"]
+    end
+    @variables begin
+        v
+    end
+    @extend v, i = oneport = OnePort(; v = v)
+    @equations begin
+        D(v) ~ i / C
+    end
 end
 
 """
-    Inductor(; name, L)
+    Inductor(; name, L, i)
 
 Creates an ideal Inductor.
+Initial current through inductor can be set with `i` ([`A`]).
 
 # States:
 
@@ -116,16 +123,18 @@ See [OnePort](@ref)
 # Parameters:
 
   - `L`: [`H`] Inductance
-  - `i_start`: [`A`] Initial current through inductor
-"""
-@component function Inductor(; name, L, i_start = 0.0)
-    @named oneport = OnePort(; i_start = i_start)
-    @unpack v, i = oneport
-    pars = @parameters L = L
-    eqs = [
-        D(i) ~ 1 / L * v,
-    ]
-    extend(ODESystem(eqs, t, [], pars; name = name), oneport)
+"""
+@mtkmodel Inductor begin
+    @parameters begin
+        L, [description = "Inductance"]
+    end
+    @variables begin
+        i
+    end
+    @extend v, i = oneport = OnePort(; i = i)
+    @equations begin
+        D(i) ~ 1 / L * v
+    end
 end
 
 """
@@ -146,13 +155,12 @@ See [TwoPort](@ref)
   - `n1` Negative pin (left port)
   - `n2` Negative pin (right port)
 """
-@component function IdealOpAmp(; name)
-    @named twoport = TwoPort()
-    @unpack v1, v2, i1, i2 = twoport
-
-    eqs = [v1 ~ 0
-        i1 ~ 0]
-    extend(ODESystem(eqs, t, [], [], name = name), twoport)
+@mtkmodel IdealOpAmp begin
+    @extend v1, v2, i1, i2 = twoport = TwoPort()
+    @equations begin
+        v1 ~ 0
+        i1 ~ 0
+    end
 end
 
 """
@@ -169,15 +177,15 @@ See [OnePort](@ref)
   - `p` Positive pin
   - `n` Negative pin
 """
-@component function Short(; name)
-    @named oneport = OnePort()
-    @unpack v, i = oneport
-    eqs = [v ~ 0]
-    extend(ODESystem(eqs, t, [], []; name = name), oneport)
+@mtkmodel Short begin
+    @extend v, i = oneport = OnePort()
+    @equations begin
+        v ~ 0
+    end
 end
 
 """
-    HeatingResistor(;name, R_ref=1.0, T_ref=300.15, alpha=0)
+    HeatingResistor(; name, R_ref = 1.0, T_ref = 300.15, alpha = 0)
 
 Temperature dependent electrical resistor
 
@@ -195,25 +203,29 @@ Temperature dependent electrical resistor
 
   - `R_ref`: [`Ω`] Reference resistance
   - `T_ref`: [K] Reference temperature
+  - `alpha`: [K⁻¹] Temperature coefficient of resistance
 """
-@component function HeatingResistor(; name, R_ref = 1.0, T_ref = 300.15, alpha = 0)
-    @named oneport = OnePort()
-    @unpack v, i = oneport
-    @named heat_port = HeatPort()
-    pars = @parameters begin
-        R_ref = R_ref
-        T_ref = T_ref
-        alpha = alpha
-    end
-    @variables R(t) = R_ref
-    eqs = [R ~ R_ref * (1 + alpha * (heat_port.T - T_ref))
+@mtkmodel HeatingResistor begin
+    @extend v, i = oneport = OnePort()
+    @components begin
+        heat_port = HeatPort()
+    end
+    @parameters begin
+        R_ref = 1.0, [description = "Reference resistance"]
+        T_ref = 300.15, [description = "Reference temperature"]
+        alpha = 0, [description = "Temperature coefficient of resistance"]
+    end
+    @variables begin
+        R(t) = R_ref
+    end
+    @equations begin
+        R ~ R_ref * (1 + alpha * (heat_port.T - T_ref))
         heat_port.Q_flow ~ -v * i # -LossPower
-        v ~ i * R]
-    extend(ODESystem(eqs, t, [R], pars; name = name, systems = [heat_port]), oneport)
+        v ~ i * R
+    end
 end
-
 """
-    EMF(;name, k)
+    EMF(; name, k)
 
 Electromotoric force (electric/mechanic transformer)
 
@@ -235,19 +247,29 @@ Electromotoric force (electric/mechanic transformer)
 
   - `k`: [`N⋅m/A`] Transformation coefficient
 """
-@component function EMF(; name, k)
-    @named p = Pin()
-    @named n = Pin()
-    @named flange = Flange()
-    @named support = Support()
-    @parameters k = k
-    @variables v(t)=0.0 i(t)=0.0 phi(t)=0.0 w(t)=0.0
-    eqs = [v ~ p.v - n.v
+@mtkmodel EMF begin
+    @components begin
+        p = Pin()
+        n = Pin()
+        flange = Flange()
+        support = Support()
+    end
+    @parameters begin
+        k, [description = "Transformation coefficient"]
+    end
+    @variables begin
+        v(t) = 0.0
+        i(t) = 0.0
+        phi(t) = 0.0
+        w(t) = 0.0
+    end
+    @equations begin
+        v ~ p.v - n.v
         0 ~ p.i + n.i
         i ~ p.i
         phi ~ flange.phi - support.phi
         D(phi) ~ w
         k * w ~ v
-        flange.tau ~ -k * i]
-    ODESystem(eqs, t, [v, i, phi, w], [k]; name = name, systems = [p, n, flange, support])
+        flange.tau ~ -k * i
+    end
 end