refactor: cut down the description of variables (#194)

- or the formatter turns them into a function

Author: ven-k

docs/src/tutorials/thermal_model.md

@@ -13,8 +13,8 @@ using ModelingToolkitStandardLibrary.Thermal, ModelingToolkit, OrdinaryDiffEq, P
 
 C1 = 15
 C2 = 15
-@named mass1 = HeatCapacitor(C = C1, T_start = 373.15)
-@named mass2 = HeatCapacitor(C = C2, T_start = 273.15)
+@named mass1 = HeatCapacitor(C = C1, T = 373.15)
+@named mass2 = HeatCapacitor(C = C2, T = 273.15)
 @named conduction = ThermalConductor(G = 10)
 @named Tsensor1 = TemperatureSensor()
 @named Tsensor2 = TemperatureSensor()

src/Thermal/HeatTransfer/ideal_components.jl

@@ -1,11 +1,11 @@
 """
-    HeatCapacitor(; name, C, T_start=273.15 + 20)
+    HeatCapacitor(; name, C, T = 273.15 + 20)
 
 Lumped thermal element storing heat
 
 # States:
 
-  - `T`: [`K`] Temperature of element
+  - `T`: [`K`] Temperature of element. It accepts an initial value, which defaults to 273.15 + 20.
   - `der_T`: [`K/s`] Time derivative of temperature
 
 # Connectors:
@@ -15,25 +15,28 @@ Lumped thermal element storing heat
 # Parameters:
 
   - `C`: [`J/K`] Heat capacity of element (= cp*m)
-  - `T_start`: [`K`] Initial temperature of element
 """
-@component function HeatCapacitor(; name, C, T_start = 273.15 + 20)
-    @named port = HeatPort()
-    @parameters C = C
-    sts = @variables begin
-        T(t) = T_start
+@mtkmodel HeatCapacitor begin
+    @components begin
+        port = HeatPort()
+    end
+    @parameters begin
+        C, [description = "Heat capacity of element"]
+    end
+    @variables begin
+        T(t) = 273.15 + 20
         der_T(t) = 0.0
     end
 
-    D = Differential(t)
-    eqs = [T ~ port.T
+    @equations begin
+        T ~ port.T
         der_T ~ port.Q_flow / C
-        D(T) ~ der_T]
-    ODESystem(eqs, t, sts, [C]; systems = [port], name = name)
+        D(T) ~ der_T
+    end
 end
 
 """
-    ThermalConductor(;name, G)
+    ThermalConductor(; name, G)
 
 Lumped thermal element transporting heat without storing it.
 
@@ -50,14 +53,14 @@ see [`Element1D`](@ref)
 
   - `G`: [`W/K`] Constant thermal conductance of material
 """
-@component function ThermalConductor(; name, G)
-    @named element1d = Element1D()
-    @unpack Q_flow, dT = element1d
-    pars = @parameters G = G
-    eqs = [
-        Q_flow ~ G * dT,
-    ]
-    extend(ODESystem(eqs, t, [], pars; name = name), element1d)
+@mtkmodel ThermalConductor begin
+    @extend Q_flow, dT = element1d = Element1D()
+    @parameters begin
+        G
+    end
+    @equations begin
+        Q_flow ~ G * dT
+    end
 end
 
 """
@@ -79,15 +82,14 @@ Lumped thermal element transporting heat without storing it.
 
   - `R`: [`K/W`] Constant thermal resistance of material
 """
-@component function ThermalResistor(; name, R)
-    @named element1d = Element1D()
-    @unpack Q_flow, dT = element1d
-    pars = @parameters R = R
-    eqs = [
-        dT ~ R * Q_flow,
-    ]
-
-    extend(ODESystem(eqs, t, [], pars; name = name), element1d)
+@mtkmodel ThermalResistor begin
+    @extend Q_flow, dT = element1d = Element1D()
+    @parameters begin
+        R
+    end
+    @equations begin
+        dT ~ R * Q_flow
+    end
 end
 
 """
@@ -109,14 +111,14 @@ Lumped thermal element for heat convection.
 
   - `G`: [W/K] Convective thermal conductance
 """
-@component function ConvectiveConductor(; name, G)
-    @named convective_element1d = ConvectiveElement1D()
-    @unpack Q_flow, dT = convective_element1d
-    @parameters G = G
-    eqs = [
-        Q_flow ~ G * dT,
-    ]
-    extend(ODESystem(eqs, t, [], [G]; name = name), convective_element1d)
+@mtkmodel ConvectiveConductor begin
+    @extend Q_flow, dT = convective_element1d = ConvectiveElement1D()
+    @parameters begin
+        G
+    end
+    @equations begin
+        Q_flow ~ G * dT
+    end
 end
 
 """
@@ -126,7 +128,7 @@ Lumped thermal element for heat convection.
 
 # States:
 
-  - `dT`:  [`K`] Temperature difference across the component `solid.T` - `fluid.T`
+  - `dT`: [`K`] Temperature difference across the component `solid.T` - `fluid.T`
   - `Q_flow`: [`W`] Heat flow rate from `solid` -> `fluid`
 
 # Connectors:
@@ -138,14 +140,14 @@ Lumped thermal element for heat convection.
 
   - `R`: [`K/W`] Constant thermal resistance of material
 """
-@component function ConvectiveResistor(; name, R)
-    @named convective_element1d = ConvectiveElement1D()
-    @unpack Q_flow, dT = convective_element1d
-    @parameters R = R
-    eqs = [
-        dT ~ R * Q_flow,
-    ]
-    extend(ODESystem(eqs, t, [], [R]; name = name), convective_element1d)
+@mtkmodel ConvectiveResistor begin
+    @extend Q_flow, dT = convective_element1d = ConvectiveElement1D()
+    @parameters begin
+        R
+    end
+    @equations begin
+        dT ~ R * Q_flow
+    end
 end
 
 """
@@ -167,22 +169,22 @@ Lumped thermal element for radiation heat transfer.
 
   - `G`: [m^2] Net radiation conductance between two surfaces # Stefan-Boltzmann constant TODO: extract into physical constants module or use existing one
 """
-@component function BodyRadiation(; name, G)
-    sigma = 5.6703744191844294e-8 # Stefan-Boltzmann constant TODO: extract into physical constants module or use existing one
-
-    @named element1d = Element1D()
-    @unpack Q_flow, dT = element1d
-    @unpack port_a, port_b = element1d
-    pars = @parameters G = G
-    eqs = [
-        Q_flow ~ G * sigma * (port_a.T^4 - port_b.T^4),
-    ]
-
-    extend(ODESystem(eqs, t, [], pars; name = name), element1d)
+@mtkmodel BodyRadiation begin
+    begin
+        sigma = 5.6703744191844294e-8 # Stefan-Boltzmann constant TODO: extract into physical constants module or use existing one
+    end
+
+    @extend Q_flow, dT, port_a, port_b = element1d = Element1D()
+    @parameters begin
+        G
+    end
+    @equations begin
+        Q_flow ~ G * sigma * (port_a.T^4 - port_b.T^4)
+    end
 end
 
 """
-    ThermalCollector(; name, m=1)
+    ThermalCollector(; name, m = 1)
 
 Collects `m` heat flows
 

src/Thermal/HeatTransfer/sensors.jl

@@ -15,12 +15,17 @@ lags are associated with this sensor model.
 
   - `port`
 """
-@component function TemperatureSensor(; name)
-    @named port = HeatPort()
-    @variables T(t)
-    eqs = [T ~ port.T
-        port.Q_flow ~ 0]
-    ODESystem(eqs, t, [T], [], systems = [port], name = name)
+@mtkmodel TemperatureSensor begin
+    @components begin
+        port = HeatPort()
+    end
+    @variables begin
+        T(t)
+    end
+    @equations begin
+        T ~ port.T
+        port.Q_flow ~ 0
+    end
 end
 
 """
@@ -40,14 +45,19 @@ output signal in kelvin.
   - `port_a`
   - `port_b`
 """
-@component function RelativeTemperatureSensor(; name)
-    @named port_a = HeatPort()
-    @named port_b = HeatPort()
-    @variables T(t)
-    eqs = [T ~ port_a.T - port_b.T
+@mtkmodel RelativeTemperatureSensor begin
+    @components begin
+        port_a = HeatPort()
+        port_b = HeatPort()
+    end
+    @variables begin
+        T(t)
+    end
+    @equations begin
+        T ~ port_a.T - port_b.T
         port_a.Q_flow ~ 0
-        port_b.Q_flow ~ 0]
-    ODESystem(eqs, t, [T], [], systems = [port_a, port_b], name = name)
+        port_b.Q_flow ~ 0
+    end
 end
 
 """
@@ -69,12 +79,17 @@ The output signal is positive, if the heat flows from `port_a` to `port_b`.
   - `port_a`
   - `port_b`
 """
-@component function HeatFlowSensor(; name)
-    @named port_a = HeatPort()
-    @named port_b = HeatPort()
-    @variables Q_flow(t)
-    eqs = [port_a.T ~ port_b.T
+@mtkmodel HeatFlowSensor begin
+    @components begin
+        port_a = HeatPort()
+        port_b = HeatPort()
+    end
+    @variables begin
+        Q_flow(t)
+    end
+    @equations begin
+        port_a.T ~ port_b.T
         port_a.Q_flow + port_b.Q_flow ~ 0
-        Q_flow ~ port_a.Q_flow]
-    ODESystem(eqs, t, [Q_flow], [], systems = [port_a, port_b], name = name)
+        Q_flow ~ port_a.Q_flow
+    end
 end

src/Thermal/HeatTransfer/sources.jl

@@ -1,5 +1,5 @@
 """
-    FixedHeatFlow(; name, Q_flow=1.0, T_ref=293.15, alpha=0.0)
+    FixedHeatFlow(; name, Q_flow = 1.0, T_ref = 293.15, alpha = 0.0)
 
 Fixed heat flow boundary condition.
 
@@ -17,18 +17,19 @@ the component FixedHeatFlow is connected, if parameter `Q_flow` is positive.
   - `T_ref`: [K] Reference temperature
   - `alpha`: [1/K] Temperature coefficient of heat flow rate
 """
-@component function FixedHeatFlow(; name, Q_flow = 1.0, T_ref = 293.15, alpha = 0.0)
-    pars = @parameters begin
-        Q_flow = Q_flow
-        T_ref = T_ref
-        alpha = alpha
+@mtkmodel FixedHeatFlow begin
+    @parameters begin
+        Q_flow = 1.0, [description = "Fixed heat flow rate at port"]
+        T_ref = 293.15, [description = "Reference temperature"]
+        alpha = 0.0, [description = "Temperature coefficient of heat flow rate"]
+    end
+    @components begin
+        port = HeatPort()
     end
-    @named port = HeatPort()
 
-    eqs = [
-        port.Q_flow ~ -Q_flow * (1 + alpha * (port.T - T_ref)),
-    ]
-    ODESystem(eqs, t, [], pars; systems = [port], name = name)
+    @equations begin
+        port.Q_flow ~ -Q_flow * (1 + alpha * (port.T - T_ref))
+    end
 end
 
 """
@@ -46,17 +47,20 @@ This model defines a fixed temperature `T` at its port in kelvin, i.e., it defin
 
   - `T`: [K] Fixed temperature boundary condition
 """
-@component function FixedTemperature(; name, T)
-    @named port = HeatPort()
-    pars = @parameters T = T
-    eqs = [
-        port.T ~ T,
-    ]
-    ODESystem(eqs, t, [], pars; systems = [port], name = name)
+@mtkmodel FixedTemperature begin
+    @components begin
+        port = HeatPort()
+    end
+    @parameters begin
+        T, [description = "Fixed temperature boundary condition"]
+    end
+    @equations begin
+        port.T ~ T
+    end
 end
 
 """
-    PrescribedHeatFlow(; name, T_ref=293.15, alpha=0.0)
+    PrescribedHeatFlow(; name, T_ref = 293.15, alpha = 0.0)
 
 Prescribed heat flow boundary condition.
 
@@ -76,18 +80,18 @@ dependent losses (which are given a reference temperature T_ref).
   - `T_ref`: [K] Reference temperature
   - `alpha`: [1/K] Temperature coefficient of heat flow rate
 """
-@component function PrescribedHeatFlow(; name, T_ref = 293.15, alpha = 0.0)
-    pars = @parameters begin
-        T_ref = T_ref
-        alpha = alpha
+@mtkmodel PrescribedHeatFlow begin
+    @parameters begin
+        T_ref = 293.15, [description = "Reference temperature"]
+        alpha = 0.0, [description = "Temperature coefficient of heat flow rate"]
+    end
+    @components begin
+        port = HeatPort()
+        Q_flow = RealInput()
+    end
+    @equations begin
+        port.Q_flow ~ -Q_flow.u * (1 + alpha * (port.T - T_ref))
     end
-    @named port = HeatPort()
-    @named Q_flow = RealInput()
-
-    eqs = [
-        port.Q_flow ~ -Q_flow.u * (1 + alpha * (port.T - T_ref)),
-    ]
-    ODESystem(eqs, t, [], pars; systems = [port, Q_flow], name = name)
 end
 
 """
@@ -104,11 +108,12 @@ the temperature at the specified value.
   - `port`
   - `RealInput` `T` input for the temperature
 """
-@component function PrescribedTemperature(; name)
-    @named port = HeatPort()
-    @named T = RealInput()
-    eqs = [
-        port.T ~ T.u,
-    ]
-    ODESystem(eqs, t, [], []; systems = [port, T], name = name)
+@mtkmodel PrescribedTemperature begin
+    @components begin
+        port = HeatPort()
+        T = RealInput()
+    end
+    @equations begin
+        port.T ~ T.u
+    end
 end