PowerFlows

Structure to perform an export from a Sienna System, plus optional updates from PowerFlowData, to the PSS/E format. Construct from a System and a PSS/E version, update using update_exporter with any new data as relevant, and perform the export with write_export. Writes a <name>.raw file and a <name>_export_metadata.json file with transformations that had to be made to conform to PSS/E naming rules, which can be parsed by PowerSystems.jl to perform a round trip with the names restored.

Arguments:

• base_system::PSY.System: the system to be exported. Later updates may change power flow-related values but may not fundamentally alter the system
• psse_version::Symbol: the version of PSS/E to target, must be one of PSSE_EXPORT_SUPPORTED_VERSIONS
• write_comments::Bool = false: whether to add the customary-but-not-in-spec-annotations after a slash on the first line and at group boundaries
• name::AbstractString = "export": the base name of the export
• step::Any = nothing: optional step data to append to the base export name. User is responsible for updating the step data. If the step data is nothing, it is not used; if it is a tuple or vector, it is joined with '' and concatted; else it is concatted after ''.
• overwrite::Bool = false: true to silently overwrite existing exports, false to throw an error if existing results are encountered

Structure containing all the data required for the evaluation of the power flows and angles, as well as these ones.

In the below descriptions, "number of buses" should be understood as "number of buses remaining, after the network reduction." Similarly, we use "arcs" instead of "branches" to distinguish between network elements (post-reduction) and system objects (pre-reduction).

Arguments:

• bus_activepower_injection::Matrix{Float64}: "(b, t)" matrix containing the bus active power injection. b: number of buses, t: number of time period.
• bus_reactivepower_injection::Matrix{Float64}: "(b, t)" matrix containing the bus reactive power injection. b: number of buses, t: number of time period.
• bus_activepower_withdrawals::Matrix{Float64}: "(b, t)" matrix containing the bus reactive power withdrawals. b: number of buses, t: number of time period.
• bus_reactivepower_withdrawals::Matrix{Float64}: "(b, t)" matrix containing the bus reactive power withdrawals. b: number of buses, t: number of time period.
• bus_activepower_constant_current_withdrawals::Matrix{Float64}: "(b, t)" matrix containing the bus active power constant current withdrawals. b: number of buses, t: number of time period.
• bus_reactivepower_constant_current_withdrawals::Matrix{Float64}: "(b, t)" matrix containing the bus reactive power constant current withdrawals. b: number of buses, t: number of time period.
• bus_activepower_constant_impedance_withdrawals::Matrix{Float64}: "(b, t)" matrix containing the bus active power constant impedance withdrawals. b: number of buses, t: number of time period.
• bus_reactivepower_constant_impedance_withdrawals::Matrix{Float64}: "(b, t)" matrix containing the bus reactive power constant impedance withdrawals. b: number of buses, t: number of time period.
• bus_reactivepower_bounds::Matrix{Float64}: "(b, t)" matrix containing upper and lower bounds for the reactive supply at each bus at each time period.
• bus_type::Matrix{PSY.ACBusTypes}: "(b, t)" matrix containing type of buses present in the system, ordered according to "bus_lookup," at each time period.
• bus_magnitude::Matrix{Float64}: "(b, t)" matrix containing the bus magnitudes, ordered according to "bus_lookup". b: number of buses, t: number of time period.
• bus_angles::Matrix{Float64}: "(b, t)" matrix containing the bus angles, ordered according to "bus_lookup". b: number of buses, t: number of time period.
• arc_activepower_flow_from_to::Matrix{Float64}: "(br, t)" matrix containing the active power flows measured at the from bus, ordered according to "arc_lookup". br: number of arcs, t: number of time period.
• arc_reactivepower_flow_from_to::Matrix{Float64}: "(br, t)" matrix containing the reactive power flows measured at the from bus, ordered according to "arc_lookup". br: number of arcs, t: number of time period.
• arc_activepower_flow_to_from::Matrix{Float64}: "(br, t)" matrix containing the active power flows measured at the to bus, ordered according to "arc_lookup". br: number of arcs, t: number of time period.
• arc_reactivepower_flow_to_from::Matrix{Float64}: "(br, t)" matrix containing the reactive power flows measured at the to bus, ordered according to "arc_lookup". br: number of arcs, t: number of time period.
• timestep_map::Dict{Int, S}: dictionary mapping the number of the time periods (corresponding to the column number of the previously mentioned matrices) and their names.
• power_network_matrix::M: matrix used for the evaluation of either the power flows or bus angles, depending on the method considered.
• aux_network_matrix::N: matrix used for the evaluation of either the power flows or bus angles, depending on the method considered.
• neighbors::Vector{Set{Int}}: Vector with the sets of adjacent buses.

Function for the definition of the PowerFlowData structure given the System data, number of time periods to consider and their names. Calling this function will not evaluate the power flows and angles. NOTE: use it for AC power flow computations.

Arguments:

• ::ACPowerFlow: use ACPowerFlow() to evaluate the AC PF.
• sys::PSY.System: container storing the system data to consider in the PowerFlowData structure.
• time_steps::Int: number of time periods to consider in the PowerFlowData structure. It defines the number of columns of the matrices used to store data. Default value = 1.
• timestep_names::Vector{String}: names of the time periods defines by the argument "time_steps". Default value = String[].

WARNING: functions for the evaluation of the multi-period AC PF still to be implemented.

Function for the definition of the PowerFlowData structure given the System data, number of time periods to consider and their names. Calling this function will not evaluate the power flows and angles. NOTE: use it for DC power flow computations.

Arguments:

• ::DCPowerFlow: use DCPowerFlow() to store the ABA matrix as powernetworkmatrix and the BA matrix as auxnetworkmatrix.
• sys::PSY.System: container storing the system data to consider in the PowerFlowData structure.
• time_steps::Int: number of time periods to consider in the PowerFlowData structure. It defines the number of columns of the matrices used to store data. Default value = 1.
• timestep_names::Vector{String}: names of the time periods defines by the argument "time_steps". Default value = String[].

Function for the definition of the PowerFlowData structure given the System data, number of time periods to consider and their names. Calling this function will not evaluate the power flows and angles. NOTE: use it for DC power flow computations.

Arguments:

• ::PTDFDCPowerFlow: use vPTDFDCPowerFlow() to store the Virtual PTDF matrix as powernetworkmatrix and the ABA matrix as auxnetworkmatrix.
• sys::PSY.System: container storing the system data to consider in the PowerFlowData structure.
• time_steps::Int: number of time periods to consider in the PowerFlowData structure. It defines the number of columns of the matrices used to store data. Default value = 1.
• timestep_names::Vector{String}: names of the time periods defines by the argument "time_steps". Default value = String[].

Sets the two PowerNetworkMatrix fields and a few others (timesteps, timestep_map), then creates arrays of default values (usually zeros) for the rest.

Calculate the paths of the (raw, metadata) files that would be written by a certain call to write_export

solve_powerflow!(pf::ACPowerFlow{<:ACPowerFlowSolverType}, system::PSY.System; kwargs...)

Solves the power flow in the system and writes the solution into the relevant structs. Updates active and reactive power setpoints for generators and active and reactive power flows for branches (calculated in the From - To direction and in the To - From direction).

Supports passing kwargs to the PF solver.

The bus types can be changed from PV to PQ if the reactive power limits are violated.

Arguments

• pf::ACPowerFlow{<:ACPowerFlowSolverType}: The power flow solver instance, can be NewtonRaphsonACPowerFlow or LUACPowerFlow (to be used for testing only).
• system::PSY.System: The power system model.
• kwargs...: Additional keyword arguments.

Keyword Arguments

• 'checkreactivepower_limits': if true, the reactive power limits are enforced by changing the respective bus types from PV to PQ. Default is false.
• tol: Infinite norm of residuals under which convergence is declared. Default is 1e-9.
• maxIterations: Maximum number of Newton-Raphson iterations. Default is 30.

Returns

• converged::Bool: Indicates whether the power flow solution converged.
• The power flow results are written into the system struct.

Examples

solve_powerflow!(pf, sys)

# Passing kwargs
solve_powerflow!(pf, sys; correct_bustypes = true)

# Passing keyword arguments
solve_powerflow!(pf, sys; maxIterations=100)

Evaluates the power flows on each system's branch and updates the PowerFlowData structure.

Arguments:

• data::PTDFPowerFlowData: PTDFPowerFlowData structure containing all the information related to the system's power flow.

Evaluates the power flows on each system's branch and updates the PowerFlowData structure.

Arguments:

• data::vPTDFPowerFlowData: vPTDFPowerFlowData structure containing all the information related to the system's power flow.

solve_powerflow!(data::ACPowerFlowData; pf::ACPowerFlow{<:ACPowerFlowSolverType} = ACPowerFlow(), kwargs...)

Solve the multiperiod AC power flow problem for the given power flow data.

The bus types can be changed from PV to PQ if the reactive power limits are violated.

Arguments

• data::ACPowerFlowData: The power flow data containing the grid information and initial conditions.
• pf::ACPowerFlow{<:ACPowerFlowSolverType}: The power flow solver type. Defaults to NewtonRaphsonACPowerFlow.
• kwargs...: Additional keyword arguments.

Keyword Arguments

• 'checkreactivepower_limits': if true, the reactive power limits are enforced by changing the respective bus types from PV to PQ. Default is false.
• time_steps: Specifies the time steps to solve. Defaults to sorting and collecting the keys of data.timestep_map.

Description

This function solves the AC power flow problem for each time step specified in data. It preallocates memory for the results and iterates over the sorted time steps. For each time step, it calls the _ac_powerflow function to solve the power flow equations and updates the data object with the results. If the power flow converges, it updates the active and reactive power injections, as well as the voltage magnitudes and angles for different bus types (REF, PV, PQ). If the power flow does not converge, it sets the corresponding entries in data to NaN. Finally, it calculates the branch power flows and updates the data object.

Notes

• If the grid topology changes (e.g., tap positions of transformers or in-service status of branches), the admittance matrices Yft and Ytf must be updated.
• If Yft and Ytf change between time steps, the branch flow calculations must be moved inside the loop.

Examples

solve_powerflow!(data)

Similar to solve_powerflow!(pf, sys) but does not update the system struct with results. Returns the results in a dictionary of dataframes.

Examples

res = solve_powerflow(pf, sys)

Evaluates the power flows on the system's branches by means of the method associated with the PowerFlowData structure data, which can be one of PTDFPowerFlowData, vPTDFPowerFlowData, or ABAPowerFlowData. Returns a dictionary of DataFrames, each containing the branch flows and bus voltages for the input PSY.System at that timestep.

Arguments:

• data::Union{PTDFPowerFlowData, vPTDFPowerFlowData, ABAPowerFlowData}: PowerFlowData structure containing the system's data per each timestep considered, as well as the associated matrix for the power flow.
• sys::PSY.System: container gathering the system data.

Evaluates the power flows on the system's branches by means of the PTDF, virtual PTDF, or DC power flow method: the type first parameter (a PTDFDCPowerFlow, vPTDFDCPowerFlow, or DCPowerFlow) selects the method to be used. Returns a dictionary containing a DataFrame for the single timestep considered, storing the branch flows and bus voltages for the input PSY.System.

Arguments:

• ::Union{PTDFDCPowerFlow, vPTDFDCPowerFlow, DCPowerFlow}: the method of power flow evaluation to be used.
• sys::PSY.System: container gathering the system data used for the evaluation of flows and angles.

Update the PSSEExporter with new data.

Arguments:

• exporter::PSSEExporter: the exporter to update
• data::PSY.PowerFlowData: the new data. Must correspond to the System with which the exporter was constructor

Update the PSSEExporter with new data.

Arguments:

• exporter::PSSEExporter: the exporter to update
• data::PSY.System: system containing the new data. Must be fundamentally the same

System as the one with which the exporter was constructed, just with different values — this is the user's responsibility, we do not exhaustively verify it.

Perform an export from the data contained in a PSSEExporter to the PSS/E file format.

Returns a dictionary containing the AC power flow results.

Only single-period evaluation is supported at the moment for AC Power flows. Resulting dictionary will therefore feature just one key linked to one DataFrame.

Arguments:

• ::ACPowerFlow: use ACPowerFlow() storing AC power flow results.
• sys::PSY.System: container storing the system information.
• result::Vector{Float64}: vector containing the results for one single time-period.

Returns a dictionary containing the DC power flow results. Each key corresponds to the name of the considered time periods, storing a DataFrame with the PF results.

Arguments:

• data::Union{PTDFPowerFlowData, vPTDFPowerFlowData, ABAPowerFlowData}: PowerFlowData structure containing power flows and bus angles.
• sys::PSY.System: container storing the system information.