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.

Arguments:

• bus_lookup::Dict{Int, Int}: dictionary linking the system's bus number with the rows of either "powernetworkmatrix" or "auxnetworkmatrix".
• branch_lookup::Dict{String, Int}: dictionary linking the branch name with the column name of either the "powernetworkmatrix" or "auxnetworkmatrix".
• 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_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.
• branch_activepower_flow_from_to::Matrix{Float64}: "(br, t)" matrix containing the active power flows measured at the from bus, ordered according to "branch_lookup". br: number of branches, t: number of time period.
• branch_reactivepower_flow_from_to::Matrix{Float64}: "(br, t)" matrix containing the reactive power flows measured at the from bus, ordered according to "branch_lookup". br: number of branches, t: number of time period.
• branch_activepower_flow_to_from::Matrix{Float64}: "(br, t)" matrix containing the active power flows measured at the to bus, ordered according to "branch_lookup". br: number of branches, t: number of time period.
• branch_reactivepower_flow_to_from::Matrix{Float64}: "(br, t)" matrix containing the reactive power flows measured at the to bus, ordered according to "branch_lookup". br: number of branches, t: number of time period.
• timestep_map::Dict{Int, S}: dictonary mapping the number of the time periods (corresponding to the column number of the previosly mentioned matrices) and their names.
• valid_ix::Vector{Int}: vector containing the indeces of not slack buses
• 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 strucure 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 argmunet "time_steps". Default value = String[].
• check_connectivity::Bool: Perform connectivity check on the network matrix. Default value = true.

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

Function for the definition of the PowerFlowData strucure 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 argmunet "time_steps". Default value = String[].
• check_connectivity::Bool: Perform connectivity check on the network matrix. Default value = true.

Function for the definition of the PowerFlowData strucure 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 argmunet "time_steps". Default value = String[].

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 KLUACPowerFlow, NLSolveACPowerFlow, or PowerFlows.LUACPowerFlow (to be used for testing only).
• system::PSY.System: The power system model.
• kwargs...: Additional keyword arguments.

Keyword Arguments

• check_connectivity::Bool: Checks if the grid is connected. Default is true.
• 'checkreactivepower_limits': if true, the reactive power limits are enforced by changing the respective bus types from PV to PQ. Default is false.
• method: (only for NLSolve) See NLSolve.jl documentation for available solvers.
• xtol: (only for NLSolve) Norm difference in x between two successive iterates under which convergence is declared. Default is 0.0.
• ftol: (only for NLSolve) Infinite norm of residuals under which convergence is declared. Default is 1e-8.
• iterations: (only for NLSolve) Maximum number of iterations. Default is 1_000.
• store_trace: (only for NLSolve) Should a trace of the optimization algorithm's state be stored? Default is false.
• show_trace: (only for NLSolve) Should a trace of the optimization algorithm's state be shown on STDOUT? Default is false.
• extended_trace: (only for NLSolve) Should additional algorithm internals be added to the state trace? Default is false.

Returns

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

Examples

solve_ac_powerflow!(pf, sys)

# Passing kwargs
solve_ac_powerflow!(pf, sys; check_connectivity=false)

# Passing NLsolve arguments
solve_ac_powerflow!(pf, sys; method=:newton)

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 netwthe grid information and initial conditions.
• pf::ACPowerFlow{<:ACPowerFlowSolverType}: The power flow solver type. Defaults to KLUACPowerFlow.
• kwargs...: Additional keyword arguments.

Keyword Arguments

• check_connectivity::Bool: Checks if the grid is connected. Default is true.
• '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.

Returns

• Nothing. The results are written directly to the data object.

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)

# Passing NLsolve arguments
res = solve_powerflow(pf, sys; method=:newton)

Evaluates the power flows on each system's branch by means of the ABA and BA matrices. Updates the PowerFlowData structure and returns a dictionary containing a DataFrame for the single timestep considered. The DataFrame containts the flows and angles related to the information stored in the PSY.System considered as input.

Arguments:

• ::DCPowerFlow: use DCPowerFlow() to evaluate the power flows according to the method based on the ABA and BA matrices
• sys::PSY.System: container gathering the system data used for the evaluation of flows and angles.

Evaluates the power flows on each system's branch by means of the PTDF matrix. Updates the PowerFlowData structure and returns a dictionary containing a DataFrame for the single timestep considered. The DataFrame containts the flows and angles related to the information stored in the PSY.System considered as input.

Arguments:

• ::PTDFDCPowerFlow: use PTDFDCPowerFlow() to evaluate the power flows according to the method based on the PTDF matrix
• sys::PSY.System: container gathering the system data used for the evaluation of flows and angles.

Evaluates the power flows on each system's branch by means of the ABA and BA matrices. Updates the PowerFlowData structure "data" and returns a dictionary containing a number of DataFrames equal to the numeber of timestep considered in "data". Each DataFrame containts the flows and angles.

Arguments:

• data::ABAPowerFlowData: PowerFlowData structure containing the system's data per each timestep considered, as well as the ABA and BA matrices.
• sys::PSY.System: container gathering the system data.

Evaluates the power flows on each system's branch by means of the PTDF matrix. Updates the PowerFlowData structure "data" and returns a dictionary containing a number of DataFrames equal to the numeber of timestep considered in "data". Each DataFrame containts the flows and angles.

Arguments:

• data::PTDFPowerFlowData: PowerFlowData structure containing the system's data per each timestep considered, as well as the PTDF matrix.
• sys::PSY.System: container gathering the system data.

Evaluates the power flows on each system's branch by means of Virtual PTDF matrices. Updates the PowerFlowData structure "data" and returns a dictionary containing a number of DataFrames equal to the numeber of timestep considered in "data". Each DataFrame containts the flows and angles.

Arguments:

• data::PTDFPowerFlowData: PowerFlowData structure containing the system data per each timestep considered, as well as the Virtual PTDF matrix.
• sys::PSY.System: container gathering the system data.

Evaluates the power flows on each system's branch by means of the Virtual PTDF matrix. Updates the PowerFlowData structure "data" and returns a dictionary containing a number of DataFrames equal to the numeber of timestep considered in "data". The DataFrame containts the flows and angles related to the information stored in the PSY.System considered as input.

Arguments:

• ::vPTDFDCPowerFlow: use vPTDFDCPowerFlow() to evaluate the power flows according to the method based on the Virtual PTDF matrix
• 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.

Peform 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 systam information.
• result::Vector{Float64}: vector containing the reults for one single time-period.

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

Arguments:

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