refactor: deprecate u_start keyword for guess

Author: AayushSabharwal

src/Blocks/math.jl

@@ -200,7 +200,7 @@ Output first input divided by second input.
 @mtkmodel Division begin
     @components begin
         input1 = RealInput()
-        input2 = RealInput(u_start = 1.0) # denominator can not be zero
+        input2 = RealInput(guess = 1.0) # denominator can not be zero
         output = RealOutput()
     end
     @equations begin

src/Blocks/sources.jl

@@ -320,13 +320,15 @@ Generate step signal.
 
   - `output`
 """
-@component function Step(; name, height = 1.0, offset = 0.0, start_time = 0.0, duration = Inf,
+@component function Step(;
+        name, height = 1.0, offset = 0.0, start_time = 0.0, duration = Inf,
         smooth = 1e-5)
     @named output = RealOutput()
     duration_numeric = duration
     pars = @parameters offset=offset start_time=start_time height=height duration=duration
     equation = if smooth == false # use comparison in case smooth is a float
-        offset + ifelse((start_time < t) & (t < start_time + duration), height, zero(height))
+        offset +
+        ifelse((start_time < t) & (t < start_time + duration), height, zero(height))
     else
         smooth === true && (smooth = 1e-5)
         if duration_numeric == Inf

src/Blocks/utils.jl

@@ -1,5 +1,11 @@
-@connector function RealInput(; name, nin = 1, u_start = nin > 1 ? zeros(nin) : 0.0)
+@connector function RealInput(;
+        name, nin = 1, u_start = nothing, guess = nin > 1 ? zeros(nin) : 0.0)
     nin > 1 && @warn "For inputs greater than one, use `RealInputArray`."
+    if u_start !== nothing
+        Base.depwarn(
+            "The keyword argument `u_start` is deprecated. Use `guess` instead.", :u_start)
+        guess = u_start
+    end
     if nin == 1
         @variables u(t) [
             input = true,
@@ -11,42 +17,53 @@
             description = "Inner variable in RealInput $name"
         ]
     end
-    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => u_start])
+    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => guess])
 end
 @doc """
-    RealInput(;name, u_start)
+    RealInput(;name, guess)
 
 Connector with one input signal of type Real.
 
 # Parameters:
-- `u_start=0`: Guess value for `u`.
+- `guess=0`: Guess value for `u`.
 
 # States:
 - `u`: Value of the connector which is a scalar.
 """ RealInput
 
-@connector function RealInputArray(; name, nin, u_start = zeros(nin))
+@connector function RealInputArray(; name, nin, u_start = nothing, guess = zeros(nin))
+    if u_start !== nothing
+        Base.depwarn(
+            "The keyword argument `u_start` is deprecated. Use `guess` instead.", :u_start)
+        guess = u_start
+    end
     @variables u(t)[1:nin] [
         input = true,
         description = "Inner variable in RealInputArray $name"
     ]
-    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => u_start])
+    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => guess])
 end
 @doc """
-    RealInputArray(;name, nin, u_start)
+    RealInputArray(;name, nin, guess)
 
 Connector with an array of input signals of type Real.
 
 # Parameters:
 - `nin`: Number of inputs.
-- `u_start=zeros(nin)`: Guess value for `u`.
+- `guess=zeros(nin)`: Guess value for `u`.
 
 # States:
 - `u`: Value of the connector which is an array.
 """ RealInputArray
 
-@connector function RealOutput(; name, nout = 1, u_start = nout > 1 ? zeros(nout) : 0.0)
+@connector function RealOutput(;
+        name, nout = 1, u_start = nothing, guess = nout > 1 ? zeros(nout) : 0.0)
     nout > 1 && @warn "For outputs greater than one, use `RealOutputArray`."
+    if u_start !== nothing
+        Base.depwarn(
+            "The keyword argument `u_start` is deprecated. Use `guess` instead.", :u_start)
+        guess = u_start
+    end
     if nout == 1
         @variables u(t) [
             output = true,
@@ -58,35 +75,40 @@ Connector with an array of input signals of type Real.
             description = "Inner variable in RealOutput $name"
         ]
     end
-    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => u_start])
+    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => guess])
 end
 @doc """
-    RealOutput(;name, u_start)
+    RealOutput(;name, guess)
 
 Connector with one output signal of type Real.
 
 # Parameters:
-- `u_start=0`: Guess value for `u`.
+- `guess=0`: Guess value for `u`.
 
 # States:
 - `u`: Value of the connector which is a scalar.
 """ RealOutput
 
-@connector function RealOutputArray(; name, nout, u_start = zeros(nout))
+@connector function RealOutputArray(; name, nout, u_start = nothing, guess = zeros(nout))
+    if u_start !== nothing
+        Base.depwarn(
+            "The keyword argument `u_start` is deprecated. Use `guess` instead.", :u_start)
+        guess = u_start
+    end
     @variables u(t)[1:nout] [
         output = true,
         description = "Inner variable in RealOutputArray $name"
     ]
-    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => u_start])
+    ODESystem(Equation[], t, [u], []; name = name, guesses = [u => guess])
 end
 @doc """
-    RealOutputArray(;name, nout, u_start)
+    RealOutputArray(;name, nout, guess)
 
 Connector with an array of output signals of type Real.
 
 # Parameters:
 - `nout`: Number of outputs.
-- `u_start=zeros(nout)`: Guess value for `u`.
+- `guess=zeros(nout)`: Guess value for `u`.
 
 # States:
 - `u`: Value of the connector which is an array.
@@ -112,8 +134,8 @@ Single input single output (SISO) continuous system block.
         y(t) = y_start, [description = "Output of SISO system"]
     end
     @components begin
-        input = RealInput(u_start = u_start)
-        output = RealOutput(u_start = y_start)
+        input = RealInput(guess = u_start)
+        output = RealOutput(guess = y_start)
     end
     @equations begin
         u ~ input.u
@@ -135,8 +157,8 @@ Base class for a multiple input multiple output (MIMO) continuous system block.
 """
 @component function MIMO(; name, nin = 1, nout = 1, u_start = zeros(nin),
         y_start = zeros(nout))
-    @named input = RealInput(nin = nin, u_start = u_start)
-    @named output = RealOutput(nout = nout, u_start = y_start)
+    @named input = RealInput(nin = nin, guess = u_start)
+    @named output = RealOutput(nout = nout, guess = y_start)
     @variables(u(t)[1:nin]=u_start, [description = "Input of MIMO system $name"],
         y(t)[1:nout]=y_start, [description = "Output of MIMO system $name"],)
     eqs = [

test/Blocks/utils.jl

@@ -3,14 +3,21 @@ using ModelingToolkit
 
 @testset "Guesses" begin
     for (block, guess) in [
-            (RealInput(; name = :a), 0.0),
-            (RealInput(; nin = 3, name = :a), zeros(3)),
-            (RealOutput(; name = :a), 0.0),
-            (RealOutput(; nout = 3, name = :a), zeros(3)),
-            (RealInputArray(; nin = 3, name = :a), zeros(3)),
-            (RealOutputArray(; nout = 3, name = :a), zeros(3)),
-        ]
+        (RealInput(; name = :a), 0.0),
+        (RealInput(; nin = 3, name = :a), zeros(3)),
+        (RealOutput(; name = :a), 0.0),
+        (RealOutput(; nout = 3, name = :a), zeros(3)),
+        (RealInputArray(; nin = 3, name = :a), zeros(3)),
+        (RealOutputArray(; nout = 3, name = :a), zeros(3))
+    ]
         guesses = ModelingToolkit.guesses(block)
         @test guesses[@nonamespace block.u] == guess
     end
 end
+
+@test_deprecated RealInput(; name = :a, u_start = 1.0)
+@test_deprecated RealInput(; name = :a, nin = 2, u_start = ones(2))
+@test_deprecated RealOutput(; name = :a, u_start = 1.0)
+@test_deprecated RealOutput(; name = :a, nout = 2, u_start = ones(2))
+@test_deprecated RealInputArray(; name = :a, nin = 2, u_start = ones(2))
+@test_deprecated RealOutputArray(; name = :a, nout = 2, u_start = ones(2))