PowerSimulationsDynamics

mutable struct BranchImpedanceChange <: Perturbation
    time::Float64
    branch_type::Type{<:PSY.ACBranch}
    branch_name::String
    multiplier::Float64
end

A BranchImpedanceChange change the impedance of a branch by a user defined multiplier. Currently there is only support for static branches disconnection, PowerSystems.Line and PowerSystems.Transformer2W. Future releases will provide support for a Dynamic Line disconnection.

Arguments:

• time::Float64 : Defines when the Branch Impedance Change will happen. This time should be inside the time span considered in the Simulation
• branch_tipe::Type{<:PowerSystems.ACBranch} : Branch type (subtype of PowerSystems.ACBranch)
• branch_name::String : User defined name for identifying the branch
• multiplier::Float64 : User defined value for impedance multiplier.

mutable struct BranchTrip <: Perturbation
    time::Float64
    branch_type::Type{<:[`PowerSystems.ACBranch`](@extref)}
    branch_name::String
end

A BranchTrip completely disconnects a branch from the system. Currently there is only support for static branches disconnection, PowerSystems.Line and PowerSystems.Transformer2W. Future releases will provide support for a Dynamic Line disconnection. Note: Islanding is currently not supported in PowerSimulationsDynamics.jl. If a BranchTrip isolates a generation unit, the system may diverge due to the isolated generator.

Arguments:

• time::Float64 : Defines when the Branch Trip will happen. This time should be inside the time span considered in the Simulation
• branch_tipe::Type{<:PowerSystems.ACBranch} : Branch type (subtype of PowerSystems.ACBranch)
• branch_name::String : User defined name for identifying the branch

Frequency-reference mode that keeps system frequency fixed at 1.0 p.u.

Use this mode when the network frequency should not track a dynamic device state during simulation.

mutable struct ControlReferenceChange <: Perturbation
    time::Float64
    device::[`PowerSystems.DynamicInjection`](@extref)
    signal::Symbol
    ref_value::Float64
end

A ControlReferenceChange allows to change the reference setpoint provided by a generator/inverter.

Arguments:

• time::Float64 : Defines when the Control Reference Change will happen. This time should be inside the time span considered in the Simulation
• device::Type{<:PowerSystems.DynamicInjection} : Dynamic device (PowerSystems.DynamicInjection)
• signal::Symbol : determines which reference setpoint will be modified. The accepted signals are:
  • :P_ref: Modifies the active power reference setpoint.
  • :V_ref: Modifies the voltage magnitude reference setpoint (if used).
  • :Q_ref: Modifies the reactive power reference setpoint (if used).
  • :ω_ref: Modifies the frequency setpoint.
• ref_value::Float64 : User defined value for setpoint reference.

mutable struct GeneratorTrip <: Perturbation
    time::Float64
    device::[`PowerSystems.DynamicInjection`](@extref)
end

A GeneratorTrip allows to disconnect a Dynamic Generation unit from the system at a specified time.

Arguments:

• time::Float64 : Defines when the Generator Trip will happen. This time should be inside the time span considered in the Simulation
• device::Type{<:PowerSystems.DynamicInjection} : Device to disconnect (PowerSystems.DynamicInjection)

mutable struct LoadChange <: Perturbation
    time::Float64
    device::[`PowerSystems.ElectricLoad`](@extref)
    signal::Symbol
    ref_value::Float64
end

A LoadChange allows to change the active or reactive power setpoint from a load.

Arguments:

• time::Float64 : Defines when the Load Change will happen. This time should be inside the time span considered in the Simulation
• device::Type{<:PowerSystems.ElectricLoad} : Load device (PowerSystems.ElectricLoad)
• signal::Symbol : determines which reference setpoint will be modified. The accepted signals are:
  • :P_ref: Modifies the active power reference setpoint.
  • :Q_ref: Modifies the reactive power reference setpoint.
• ref_value::Float64 : User defined value for setpoint reference.

mutable struct LoadTrip <: Perturbation
    time::Float64
    device::[`PowerSystems.ElectricLoad`](@extref)
end

A LoadTrip allows the user to disconnect a load from the system.

Arguments:

• time::Float64 : Defines when the Generator Trip will happen. This time should be inside the time span considered in the Simulation
• device::Type{<:PowerSystems.ElectricLoad} : Load to disconnect (PowerSystems.ElectricLoad)

Instantiate a MassMatrixModel for ODE inputs.

Instantiate a MassMatrixModel for ForwardDiff calculations

function NetworkSwitch(
    time::Float64,
    ybus::SparseArrays.SparseMatrixCSC{Complex{Float64}, Int},
)

Allows to modify directly the admittance matrix, Ybus, used in the Simulation. This allows the user to perform branch modifications, three phase faults (with impedance larger than zero) or branch trips, as long as the new Ybus provided captures that perturbation.

Arguments:

• time::Float64 : Defines when the Network Switch will happen. This time should be inside the time span considered in the Simulation
• ybus::SparseArrays.SparseMatrixCSC{Complex, Int} : Complex admittance matrix

function PerturbState(
    time::Float64,
    index::Int,
    value::Float64,
)

Allows the user to modify the state index by adding value. The user should modify dynamic states only, since algebraic state may require to do a reinitialization.

Arguments:

• time::Float64 : Defines when the modification of the state will happen. This time should be inside the time span considered in the Simulation.
• index::Int : Defines which state index you want to modify
• value::Float64 : Defines how much the state will increase in value

Frequency-reference mode that tracks the frequency state at the reference bus.

If a dynamic injector at the slack bus provides a compatible frequency state, that state is used as the network frequency reference.

Instantiate an ResidualModel for ODE inputs.

Instantiate an ResidualModel for ForwardDiff calculations

function Simulation
    ::SimulationModel
    system::[`PowerSystems.System`](@extref)
    simulation_folder::String
    tspan::NTuple{2, Float64},
    perturbations::Vector{<:Perturbation} = Vector{Perturbation}();
    kwargs...,
end

Builds the simulation object and conducts the indexing process. The original system is not modified and a copy its created and stored in the Simulation.

Arguments:

• ::SimulationModel : Type of Simulation Model. ResidualModel or MassMatrixModel.
• system: PowerSystems.System — power system data
• simulation_folder::String : Folder directory
• tspan::NTuple{2, Float64} : Time span for simulation
• perturbations::Vector{<:Perturbation} : Vector of Perturbations for the Simulation. Default: No Perturbations
• initialize_simulation::Bool : Runs the initialization routine. If false, simulation runs based on the operating point stored in PowerSystems.System
• initial_conditions::Vector{Float64} : Allows the user to pass a vector with the initial condition values desired in the simulation. If initialize_simulation = true, these values are used as a first guess and overwritten.
• frequency_reference : Default ReferenceBus. Determines which frequency model is used for the network. Currently there are two options available:
  • ConstantFrequency assumes that the network frequency is 1.0 per unit at all times.
  • ReferenceBus will use the frequency state of a Dynamic Generator (rotor speed) or Dynamic Inverter (virtual speed) connected to the Reference Bus (defined in the Power Flow data) as the network frequency. If multiple devices are connected to such bus, the device with larger base power will be used as a reference. If a Voltage Source is connected to the Reference Bus, then a ConstantFrequency model will be used.
• system_to_file::Bool : Default false. Serializes the initialized system
• console_level::Logging : Default Logging.Warn. Sets the level of logging output to the console. Can be set to Logging.Error, Logging.Warn, Logging.Info or Logging.Debug
• file_level::Logging : Default Logging.Info. Sets the level of logging output to file. Can be set to Logging.Error, Logging.Warn, Logging.Info or Logging.Debug
• disable_timer_outputs::Bool : Default false. Allows the user to display timer information about the construction and initilization of the Simulation.

Container for the output of a dynamic simulation run.

SimulationResults stores the solved trajectory together with lookup structures used by post-processing utilities (state maps, bus lookup, setpoints, and auxiliary pointers).

mutable struct SourceBusVoltageChange <: Perturbation
    time::Float64
    device::PSY.Source
    signal::Symbol
    ref_value::Float64
end

A SourceBusVoltageChange allows to change the reference setpoint provided by a voltage source.

Arguments:

• time::Float64 : Defines when the Control Reference Change will happen. This time should be inside the time span considered in the Simulation
• device::Type{<:PowerSystems.Source} : Voltage source device (PowerSystems.Source)
• signal::Symbol : determines which reference setpoint will be modified. The accepted signals are:
  • :V_ref Modifies the internal voltage magnitude reference setpoint.
  • :θ_ref Modifies the internal voltage angle reference setpoint.
• ref_value::Float64 : User defined value for setpoint reference.

function Simulation!
    ::SimulationModel
    system::[`PowerSystems.System`](@extref)
    simulation_folder::String
    tspan::NTuple{2, Float64},
    perturbations::Vector{<:Perturbation} = Vector{Perturbation}();
    kwargs...,
end

Builds the simulation object and conducts the indexing process. The initial conditions are stored in the system.

Arguments:

• ::SimulationModel : Type of Simulation Model. ResidualModel or MassMatrixModel.
• system: PowerSystems.System — power system data
• simulation_folder::String : Folder directory
• tspan::NTuple{2, Float64} : Time span for simulation
• perturbations::Vector{<:Perturbation} : Vector of Perturbations for the Simulation. Default: No Perturbations
• initialize_simulation::Bool : Runs the initialization routine. If false, simulation runs based on the operating point stored in PowerSystems.System
• initial_conditions::Vector{Float64} : Allows the user to pass a vector with the initial condition values desired in the simulation. If initialize_simulation = true, these values are used as a first guess and overwritten.
• frequency_reference : Default ReferenceBus. Determines which frequency model is used for the network. Currently there are two options available:
  • ConstantFrequency assumes that the network frequency is 1.0 per unit at all times.
  • ReferenceBus will use the frequency state of a Dynamic Generator (rotor speed) or Dynamic Inverter (virtual speed) connected to the Reference Bus (defined in the Power Flow data) as the network frequency. If multiple devices are connected to such bus, the device with larger base power will be used as a reference. If a Voltage Source is connected to the Reference Bus, then a ConstantFrequency model will be used.
• system_to_file::Bool : Default false. Serializes the initialized system
• console_level::Logging : Default Logging.Warn. Sets the level of logging output to the console. Can be set to Logging.Error, Logging.Warn, Logging.Info or Logging.Debug
• file_level::Logging : Default Logging.Info. Sets the level of logging output to file. Can be set to Logging.Error, Logging.Warn, Logging.Info or Logging.Debug
• disable_timer_outputs::Bool : Default false. Allows the user to display timer information about the construction and initilization of the Simulation.

execute!(
    sim::Simulation,
    solver;
    kwargs...
)

Solves the time-domain dynamic simulation model.

Arguments

• sim: Simulation — initialized simulation object
• solver: solver used for numerical integration; must match the formulation (e.g. solvers for ResidualModel vs MassMatrixModel)
• enable_progress_bar::Bool : Default: true. Enables progress bar for the integration routine.
• Additional solver keyword arguments can be included. See Common Solver Options in the DifferentialEquations.jl documentation for more details.

get_activepower_branch_flow(
        res::SimulationResults,
        name::String,
        location::Symbol,
)

Function to obtain the active power flowing through the series element of a Branch. The user must specified is the power should be computed in the :from or to :bus, by specifying a symbol.

If :from is specified, the power is computed flowing outwards the :from bus. If :to is specified, the power is computed flowing into the :to bus.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified line
• location::Symbol : :from or :to to specify a bus

get_activepower_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the active power output time series of a Dynamic Injection series out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_field_current_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the field current time series of a Dynamic Generator out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_field_voltage_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the field voltage time series of a Dynamic Generator out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_frequency_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the frequency time series of a Dynamic Injection out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_imaginary_current_branch_flow(
        res::SimulationResults,
        name::String,
)

Function to obtain the imaginary current flowing through the series element of a Branch

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified line

get_imaginary_current_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the imaginary current time series of a Dynamic Injection series out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

function get_jacobian(
::Type{T},
system::[`PowerSystems.System`](@extref),
sparse_retrieve_loop::Int = 3,
) where {T <: SimulationModel}

Returns the jacobian function of the system model resulting from the system data.

Arguments:

• ::SimulationModel : Type of Simulation Model. ResidualModel or MassMatrixModel.
• system: PowerSystems.System — power system data
• sparse_retrieve_loop::Int : Number of loops for sparsity detection. If 0, builds the Jacobian with a DenseMatrix

get_mechanical_torque_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the mechanical torque time series of the mechanical torque out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_pss_output_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the pss output time series of a Dynamic Generator out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_reactivepower_branch_flow(
        res::SimulationResults,
        name::String,
        location::Symbol,
)

Function to obtain the reactive power flowing through the series element of a Branch. The user must specified is the power should be computed in the :from or to :bus, by specifying a symbol.

If :from is specified, the power is computed flowing outwards the :from bus. If :to is specified, the power is computed flowing into the :to bus.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified line
• location::Symbol : :from or :to to specify a bus

get_reactivepower_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the reactive power output time series of a Dynamic Injection series out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_real_current_branch_flow(
        res::SimulationResults,
        name::String,
)

Function to obtain the real current flowing through the series element of a Branch

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified line

get_real_current_series(
        res::SimulationResults,
        name::String,
)

Function to obtain the real current time series of a Dynamic Injection series out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• name::String : Name to identify the specified device

get_setpoints(sim::Simulation)

Function that returns the reference setpoints for all the dynamic devices.

Arguments

• sim: Simulation — object that contains the initial condition and setpoints

Function to obtain output imaginary current for a source. It receives the simulation results, the Source name and an optional argument of the time step of the results.

Function to obtain output real current for a source. It receives the simulation results, the Source name and an optional argument of the time step of the results.

get_state_series(
    res::SimulationResults,
    ref::Tuple{String, Symbol};
    dt::Union{Nothing, Float64, Vector{Float64}} = nothing,
    unique_timestamps::Bool = true,
)
end

Function to obtain series of states out of DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• ref:Tuple{String, Symbol} : Tuple used to identify the dynamic device, via its name, as a String, and the associated state as a Symbol.

get_voltage_angle_series(
    res::SimulationResults,
    bus_number::Int
)

Function to obtain the voltage angle series out of the DAE Solution.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution
• bus_number::Int : Bus number identifier

get_voltage_magnitude_series(
    res::SimulationResults,
    bus_number::Int
)

Function to obtain the voltage magnitude series out of the DAE Solution.

Arguments:

• res::SimulationResults : Simulation Results object that contains the solution
• bus_number::Int : Bus number identifier

Returns a Dictionary with the resulting initial conditions of the simulation

read_results(sim::Simulation)

Return the SimulationResults stored in sim after execute! completes (or the last available results object).

Arguments

• sim: Simulation to read from

show_states_initial_value(res::SimulationResults)

Function to print initial states.

Arguments

• res::SimulationResults : Simulation Results object that contains the solution

show_states_initial_value(sim::Simulation)

Function to print initial states.

Arguments

• sim::Simulation : Simulation object that contains the initial condition

small_signal_analysis(
        sim::Simulation,
)

Returns the small-signal output object that contains the eigenvalues and participation factors.

Arguments

• sim: Simulation for a system without time delays

summary_eigenvalues(
        sm::SmallSignalOutput,
)

Function to obtain a summary of the eigenvalues of the Jacobian at the operating point. It returns a DataFrame with the most associated state for each eigenvalue, its real and imaginary part, damping and frequency.

Arguments

• sm::SmallSignalOutput : Small Signal Output object that contains the eigenvalues and participation factors

summary_participation_factors(
        sm::SmallSignalOutput,
)

Function to obtain the participation factor of each state to each eigenvalue. It returns a DataFrame with the participation factors of each state to all eigenvalues.

Arguments

• sm::SmallSignalOutput : Small Signal Output object that contains the eigenvalues and participation factors