PowerSimulationsDynamics

PowerSimulationsDynamics.BranchImpedanceChangeType
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} : Type of branch modified
  • branch_name::String : User defined name for identifying the branch
  • multiplier::Float64 : User defined value for impedance multiplier.
source
PowerSimulationsDynamics.BranchTripType
mutable struct BranchTrip <: Perturbation
    time::Float64
    branch_type::Type{<:PowerSystems.ACBranch}
    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} : Type of branch disconnected
  • branch_name::String : User defined name for identifying the branch
source
PowerSimulationsDynamics.ControlReferenceChangeType
mutable struct ControlReferenceChange <: Perturbation
    time::Float64
    device::PowerSystems.DynamicInjection
    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 modified
  • 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.
source
PowerSimulationsDynamics.GeneratorTripType
mutable struct GeneratorTrip <: Perturbation
    time::Float64
    device::PowerSystems.DynamicInjection
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 be disconnected
source
PowerSimulationsDynamics.LoadChangeType
mutable struct LoadChange <: Perturbation
    time::Float64
    device::PowerSystems.ElectricLoad
    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} : Dynamic device modified
  • 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.
source
PowerSimulationsDynamics.LoadTripType
mutable struct LoadTrip <: Perturbation
    time::Float64
    device::PowerSystems.ElectricLoad
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} : Device to be disconnected
source
PowerSimulationsDynamics.NetworkSwitchType
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{Float64}, Int} : Complex admittance matrix
source
PowerSimulationsDynamics.PerturbStateType
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
source
PowerSimulationsDynamics.SimulationMethod
function Simulation
    ::SimulationModel
    system::PowerSystems.System
    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. See Models Section for more details
  • system::PowerSystems.System : 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 operation point stored in 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.
source
PowerSimulationsDynamics.SourceBusVoltageChangeType
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} : Device modified
  • 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.
source
PowerSimulationsDynamics.Simulation!Method
function Simulation!
    ::SimulationModel
    system::PowerSystems.System
    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. See Models Section for more details
  • system::PowerSystems.System : 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 operation point stored in 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.
source
PowerSimulationsDynamics.execute!Method
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 be passed correctly depending on the Type of Simulation Model
  • 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.
source
PowerSimulationsDynamics.get_activepower_branch_flowMethod
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
source
PowerSimulationsDynamics.get_activepower_seriesMethod
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
source
PowerSimulationsDynamics.get_field_current_seriesMethod
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
source
PowerSimulationsDynamics.get_field_voltage_seriesMethod
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
source
PowerSimulationsDynamics.get_frequency_seriesMethod
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
source
PowerSimulationsDynamics.get_imaginary_current_branch_flowMethod
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
source
PowerSimulationsDynamics.get_imaginary_current_seriesMethod
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
source
PowerSimulationsDynamics.get_jacobianMethod
function get_jacobian(
::Type{T},
system::PSY.System,
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. See Models Section for more details
  • system::PowerSystems.System : System data
  • sparse_retrieve_loop::Int : Number of loops for sparsity detection. If 0, builds the Jacobian with a DenseMatrix
source
PowerSimulationsDynamics.get_mechanical_torque_seriesMethod
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
source
PowerSimulationsDynamics.get_pss_output_seriesMethod
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
source
PowerSimulationsDynamics.get_reactivepower_branch_flowMethod
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
source
PowerSimulationsDynamics.get_reactivepower_seriesMethod
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
source
PowerSimulationsDynamics.get_real_current_branch_flowMethod
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
source
PowerSimulationsDynamics.get_real_current_seriesMethod
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
source
PowerSimulationsDynamics.get_setpointsMethod
get_setpoints(sim::Simulation)

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

Arguments

  • sim::Simulation : Simulation object that contains the initial condition and setpoints.
source
PowerSimulationsDynamics.get_state_seriesMethod
get_state_series(
    res::SimulationResults,
    ref::Tuple{String, Symbol};
    dt::Union{Nothing, Float64, Vector{Float64}} = nothing
)
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.
source
PowerSimulationsDynamics.get_voltage_angle_seriesMethod
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
source
PowerSimulationsDynamics.get_voltage_magnitude_seriesMethod
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
source
PowerSimulationsDynamics.small_signal_analysisMethod
small_signal_analysis(
        sim::Simulation,
)

Returns the Small Signal Output object that contains the eigenvalues and participation factors.

Arguments

  • sim::Simulation : Small Signal Output object that contains the eigenvalues and participation factors
source
PowerSimulationsDynamics.summary_eigenvaluesMethod
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
source
PowerSimulationsDynamics.summary_participation_factorsMethod
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
source