add DEGOV

docs/make.jl

@@ -22,6 +22,7 @@ makedocs(;
         "Small Signal" => "small.md",
         "Reference Frames" => "reference_frames.md",
         "Perturbations" => "perturbations.md",
+        "Time Delays" => "time_delays.md",
         "Industrial Renewable Models" => "generic.md",
         "Generator Component Library" => Any[
             "Machine" => "component_models/machines.md",

docs/src/time_delays.md

@@ -0,0 +1,22 @@
+# Delays
+
+PowerSimulationsDynamics supports models with constant delays in a mass matrix formulation:
+
+```math
+\begin{align}
+M\frac{dx(t)}{dt} = f(x(t), x(t-\tau_1), ... , x(t-\tau_N))   
+\end{align}
+```
+
+For more information on solving such models, refer to the documentation for [DelayDiffEq.jl](https://github.com/SciML/DelayDiffEq.jl) package.
+
+The following models include time delays:
+
+* `DEGOV`
+
+There is currently limited support for including models with time delays. The following limitations apply:
+
+* Only constant delays are supported (state dependent delays are not).
+* System models with delays must use `MassMatrixModel`  formulation (`ResidualModel` is not currently compatible).
+* System models with delays are not compatible with small signal analysis tools.
+* The system formulation with delays is not compatible with automatic differentiation for calculating the gradient with respect to time. The setting `autodiff=false` should be set when passing the solver (e.g. `MethodofSteps(Rodas5(autodiff=false))`).

src/base/device_wrapper.jl

@@ -20,6 +20,12 @@ index(::Type{<:PSY.InnerControl}) = 4
 index(::Type{<:PSY.Converter}) = 5
 index(::Type{<:PSY.Filter}) = 6
 
+get_delays(::PSY.DynamicInjection) = nothing
+get_delays(
+    dynamic_injector::PSY.DynamicGenerator{M, S, A, PSY.DEGOV, P},
+) where {M <: PSY.Machine, S <: PSY.Shaft, A <: PSY.AVR, P <: PSY.PSS} =
+    [PSY.get_Td(PSY.get_prime_mover(dynamic_injector))]
+
 """
 Wraps DynamicInjection devices from PowerSystems to handle changes in controls and connection
 status, and allocate the required indexes of the state space.
@@ -39,6 +45,7 @@ struct DynamicWrapper{T <: PSY.DynamicInjection}
     ix_range::Vector{Int}
     ode_range::Vector{Int}
     bus_ix::Int
+    bus_size::Int
     global_index::Base.ImmutableDict{Symbol, Int}
     component_state_mapping::Base.ImmutableDict{Int, Vector{Int}}
     input_port_mapping::Base.ImmutableDict{Int, Vector{Int}}
@@ -59,6 +66,7 @@ struct DynamicWrapper{T <: PSY.DynamicInjection}
         ix_range,
         ode_range,
         bus_ix::Int,
+        bus_size::Int,
         global_index::Base.ImmutableDict{Symbol, Int},
         component_state_mapping::Base.ImmutableDict{Int, Vector{Int}},
         input_port_mapping::Base.ImmutableDict{Int, Vector{Int}},
@@ -81,6 +89,7 @@ struct DynamicWrapper{T <: PSY.DynamicInjection}
             Vector{Int}(ix_range),
             Vector{Int}(ode_range),
             bus_ix,
+            bus_size,
             global_index,
             component_state_mapping,
             input_port_mapping,
@@ -113,6 +122,7 @@ function DynamicWrapper(
     device::T,
     dynamic_device::D,
     bus_ix::Int,
+    bus_size::Int,
     ix_range,
     ode_range,
     inner_var_range,
@@ -146,6 +156,7 @@ function DynamicWrapper(
         ix_range,
         ode_range,
         bus_ix,
+        bus_size,
         Base.ImmutableDict(
             sort!(device_states .=> ix_range; by = x -> x.second, rev = true)...,
         ),
@@ -167,6 +178,7 @@ function DynamicWrapper(
     device::PSY.ThermalStandard,
     dynamic_device::PSY.AggregateDistributedGenerationA,
     bus_ix::Int,
+    bus_size::Int,
     ix_range,
     ode_range,
     inner_var_range,
@@ -194,6 +206,7 @@ function DynamicWrapper(
         ix_range,
         ode_range,
         bus_ix,
+        bus_size,
         Base.ImmutableDict(
             sort!(device_states .=> ix_range; by = x -> x.second, rev = true)...,
         ),
@@ -215,6 +228,7 @@ function DynamicWrapper(
     device::PSY.Source,
     dynamic_device::D,
     bus_ix::Int,
+    bus_size::Int,
     ix_range,
     ode_range,
     inner_var_range,
@@ -240,6 +254,7 @@ function DynamicWrapper(
         collect(ix_range),
         collect(ode_range),
         bus_ix,
+        bus_size,
         Base.ImmutableDict(Dict(device_states .=> ix_range)...),
         Base.ImmutableDict{Int, Vector{Int}}(),
         Base.ImmutableDict{Int, Vector{Int}}(),

src/base/jacobian.jl

@@ -3,6 +3,7 @@
 # in SparseDiffTools
 
 struct JacobianFunctionWrapper{
+    D <: DelayModel,
     F,
     T <: Union{Matrix{Float64}, SparseArrays.SparseMatrixCSC{Float64, Int64}},
 } <: Function
@@ -13,12 +14,12 @@ struct JacobianFunctionWrapper{
 end
 
 # This version of the function is type unstable should only be used for non-critial ops
-function (J::JacobianFunctionWrapper)(x::AbstractVector{Float64})
+function (J::JacobianFunctionWrapper{NoDelays})(x::AbstractVector{Float64})
     J.x .= x
     return J.Jf(J.Jv, x)
 end
 
-function (J::JacobianFunctionWrapper)(
+function (J::JacobianFunctionWrapper{NoDelays})(
     JM::U,
     x::AbstractVector{Float64},
 ) where {U <: Union{Matrix{Float64}, SparseArrays.SparseMatrixCSC{Float64, Int64}}}
@@ -27,7 +28,17 @@ function (J::JacobianFunctionWrapper)(
     return
 end
 
-function (J::JacobianFunctionWrapper)(
+function (J::JacobianFunctionWrapper{HasDelays})(
+    JM::U,
+    x::AbstractVector{Float64},
+) where {U <: Union{Matrix{Float64}, SparseArrays.SparseMatrixCSC{Float64, Int64}}}
+    h(p, t; idxs = nothing) = typeof(idxs) <: Number ? x[idxs] : x
+    J.x .= x
+    J.Jf(JM, x, h, 0.0)
+    return
+end
+
+function (J::JacobianFunctionWrapper{NoDelays})(
     JM::U,
     x::AbstractVector{Float64},
     p,
@@ -37,7 +48,29 @@ function (J::JacobianFunctionWrapper)(
     return
 end
 
-function (J::JacobianFunctionWrapper)(
+function (J::JacobianFunctionWrapper{HasDelays})(
+    JM::U,
+    x::AbstractVector{Float64},
+    h,
+    p,
+    t,
+) where {U <: Union{Matrix{Float64}, SparseArrays.SparseMatrixCSC{Float64, Int64}}}
+    J.Jf(JM, x, h, t)
+    return
+end
+
+function (J::JacobianFunctionWrapper{NoDelays})(
+    JM::U,
+    x::AbstractVector{Float64},
+    h,
+    p,
+    t,
+) where {U <: Union{Matrix{Float64}, SparseArrays.SparseMatrixCSC{Float64, Int64}}}
+    J.Jf(JM, x, h, t)
+    return
+end
+
+function (J::JacobianFunctionWrapper{NoDelays})(
     JM::U,
     dx::AbstractVector{Float64},
     x::AbstractVector{Float64},
@@ -53,7 +86,7 @@ function (J::JacobianFunctionWrapper)(
 end
 
 function JacobianFunctionWrapper(
-    m!::SystemModel{MassMatrixModel},
+    m!::SystemModel{MassMatrixModel, NoDelays},
     x0_guess::Vector{Float64};
     # Improve the heuristic to do sparsity detection
     sparse_retrieve_loop::Int = 0, #max(3, length(x0_guess) ÷ 100),
@@ -84,7 +117,12 @@ function JacobianFunctionWrapper(
     end
     Jf(Jv, x0)
     mass_matrix = get_mass_matrix(m!.inputs)
-    return JacobianFunctionWrapper{typeof(Jf), typeof(Jv)}(Jf, Jv, x0, mass_matrix)
+    return JacobianFunctionWrapper{NoDelays, typeof(Jf), typeof(Jv)}(
+        Jf,
+        Jv,
+        x0,
+        mass_matrix,
+    )
 end
 
 function JacobianFunctionWrapper(
@@ -119,7 +157,53 @@ function JacobianFunctionWrapper(
     end
     Jf(Jv, x0)
     mass_matrix = get_mass_matrix(m!.inputs)
-    return JacobianFunctionWrapper{typeof(Jf), typeof(Jv)}(Jf, Jv, x0, mass_matrix)
+    return JacobianFunctionWrapper{NoDelays, typeof(Jf), typeof(Jv)}(
+        Jf,
+        Jv,
+        x0,
+        mass_matrix,
+    )
+end
+
+function JacobianFunctionWrapper(
+    m!::SystemModel{MassMatrixModel, HasDelays},
+    x0_guess::Vector{Float64};
+    # Improve the heuristic to do sparsity detection
+    sparse_retrieve_loop::Int = 0, #max(3, length(x0_guess) ÷ 100),
+)
+    x0 = deepcopy(x0_guess)
+    n = length(x0)
+    Jf =
+        (Jv, x, h, t) -> begin
+            @debug "Evaluating Jacobian Function"
+            m_ = (residual, x) -> m!(residual, x, h, nothing, t)
+            jconfig =
+                ForwardDiff.JacobianConfig(m_, similar(x0), x0, ForwardDiff.Chunk(x0))
+            ForwardDiff.jacobian!(Jv, m_, zeros(n), x, jconfig)
+            return
+        end
+    jac = zeros(n, n)
+    if sparse_retrieve_loop > 0
+        for _ in 1:sparse_retrieve_loop
+            temp = zeros(n, n)
+            rng_state = copy(Random.default_rng())
+            Jf(temp, x0 + Random.randn(n))
+            copy!(Random.default_rng(), rng_state)
+            jac .+= abs.(temp)
+        end
+        Jv = SparseArrays.sparse(jac)
+    elseif sparse_retrieve_loop == 0
+        Jv = jac
+    else
+        throw(IS.ConflictingInputsError("negative sparse_retrieve_loop not valid"))
+    end
+    mass_matrix = get_mass_matrix(m!.inputs)
+    return JacobianFunctionWrapper{HasDelays, typeof(Jf), typeof(Jv)}(
+        Jf,
+        Jv,
+        x0,
+        mass_matrix,
+    )
 end
 
 function get_jacobian(

src/base/nlsolve_wrapper.jl

@@ -8,11 +8,25 @@ NLsolveWrapper() = NLsolveWrapper(Vector{Float64}(), false, true)
 converged(sol::NLsolveWrapper) = sol.converged
 failed(sol::NLsolveWrapper) = sol.failed
 
-function _get_model_closure(model::SystemModel{MassMatrixModel}, ::Vector{Float64})
+function _get_model_closure(
+    model::SystemModel{MassMatrixModel, NoDelays},
+    ::Vector{Float64},
+)
     return (residual, x) -> model(residual, x, nothing, 0.0)
 end
 
-function _get_model_closure(model::SystemModel{ResidualModel}, x0::Vector{Float64})
+function _get_model_closure(
+    model::SystemModel{MassMatrixModel, HasDelays},
+    x0::Vector{Float64},
+)
+    h(p, t; idxs = nothing) = typeof(idxs) <: Number ? x0[idxs] : x0
+    return (residual, x) -> model(residual, x, h, nothing, 0.0)
+end
+
+function _get_model_closure(
+    model::SystemModel{ResidualModel, NoDelays},
+    x0::Vector{Float64},
+)
     dx0 = zeros(length(x0))
     return (residual, x) -> model(residual, dx0, x, nothing, 0.0)
 end

src/base/simulation.jl

@@ -289,7 +289,10 @@ end
 function _get_jacobian(sim::Simulation{MassMatrixModel})
     inputs = get_simulation_inputs(sim)
     x0_init = get_initial_conditions(sim)
-    return JacobianFunctionWrapper(MassMatrixModel(inputs, x0_init, JacobianCache), x0_init)
+    return JacobianFunctionWrapper(
+        MassMatrixModel(inputs, x0_init, JacobianCache),
+        x0_init,
+    )
 end
 
 function _build_perturbations!(sim::Simulation)
@@ -329,7 +332,7 @@ end
 
 function _get_diffeq_problem(
     sim::Simulation,
-    model::SystemModel{ResidualModel},
+    model::SystemModel{ResidualModel, NoDelays},
     jacobian::JacobianFunctionWrapper,
 )
     x0 = get_initial_conditions(sim)
@@ -354,7 +357,7 @@ end
 
 function _get_diffeq_problem(
     sim::Simulation,
-    model::SystemModel{MassMatrixModel},
+    model::SystemModel{MassMatrixModel, NoDelays},
     jacobian::JacobianFunctionWrapper,
 )
     simulation_inputs = get_simulation_inputs(sim)
@@ -375,6 +378,37 @@ function _get_diffeq_problem(
     return
 end
 
+function get_history_function(simulation_inputs)
+    x0 = get_initial_conditions(simulation_inputs)
+    h(p, t; idxs = nothing) = typeof(idxs) <: Number ? x0[idxs] : x0
+    return h
+end
+
+function _get_diffeq_problem(
+    sim::Simulation,
+    model::SystemModel{MassMatrixModel, HasDelays},
+    jacobian::JacobianFunctionWrapper,
+)
+    simulation_inputs = get_simulation_inputs(sim)
+    h = get_history_function(sim)
+    sim.problem = SciMLBase.DDEProblem(
+        SciMLBase.DDEFunction{true}(
+            model;
+            mass_matrix = get_mass_matrix(simulation_inputs),
+            jac = jacobian,
+            jac_prototype = jacobian.Jv,
+        ),
+        sim.x0_init,
+        h,
+        get_tspan(sim),
+        simulation_inputs;
+        constant_lags = filter!(x -> x != 0, unique(simulation_inputs.delays)),
+    )
+    sim.status = BUILT
+
+    return
+end
+
 function _build!(sim::Simulation{T}; kwargs...) where {T <: SimulationModel}
     check_kwargs(kwargs, SIMULATION_ACCEPTED_KWARGS, "Simulation")
     # Branches are a super set of Lines. Passing both kwargs will
@@ -417,7 +451,7 @@ function _build!(sim::Simulation{T}; kwargs...) where {T <: SimulationModel}
                     model = T(simulation_inputs, get_initial_conditions(sim), SimCache)
                 end
                 TimerOutputs.@timeit BUILD_TIMER "Initial Condition NLsolve refinement" begin
-                    refine_initial_condition!(sim, model, jacobian)
+                    refine_initial_condition!(sim, model, jacobian)    #Jacobian errors 
                 end
                 TimerOutputs.@timeit BUILD_TIMER "Build Perturbations" begin
                     _build_perturbations!(sim)