PowerFlows

A struct for evaluating power flow solutions in AC systems.

This struct is parameterized by the type of AC power flow solver to use, which must be a subtype of ACPowerFlowSolverType. It also contains a few fields that control whether to compute certain additional data, like loss factors: see the constructor for details.

ACPowerFlow{ACSolver}(
    check_reactive_power_limits::Bool = false,
    exporter::Union{Nothing, PowerFlowEvaluationModel} = nothing,
    calculate_loss_factors::Bool = false,
    generator_slack_participation_factors::Union{
        Nothing,
        Dict{Tuple{DataType, String}, Float64},
        Vector{Dict{Tuple{DataType, String}, Float64}},
    } = nothing,
) where {ACSolver <: ACPowerFlowSolverType}

An evaluation model for a standard AC powerflow with the specified solver type.

Arguments

• ACSolver: The type of AC power flow solver to use, which must be a subtype of ACPowerFlowSolverType. Default is NewtonRaphsonACPowerFlow.
• check_reactive_power_limits::Bool: Whether to check reactive power limits during the power flow solution. Default is false.
• exporter::Union{Nothing, PowerFlowEvaluationModel}: An optional exporter for the power flow results. If not nothing, it should be a PSSEExportPowerFlow.
• calculate_loss_factors::Bool: Whether to calculate loss factors during the power flow solution. Default is false.
• generator_slack_participation_factors::Union{Nothing, Dict{Tuple{DataType, String}, Float64}, Vector{Dict{Tuple{DataType, String}, Float64}}}: An optional parameter that specifies the participation factors for generator slack in the power flow solution. If nothing, all slack is picked up by the reference bus. If a Dict, it should map (component_type, component_name) tuples to participation factors. If a Vector, it should contain multiple such dictionaries, allowing for different participation factors for different time steps.

An abstract supertype for all iterative methods. Subtypes: NewtonRaphsonACPowerFlow, TrustRegionACPowerFlow, LevenbergMarquardtACPowerFlow, and RobustHomotopyPowerFlow.

An abstract supertype for all DC power flow evaluation models. Subtypes: DCPowerFlow, PTDFDCPowerFlow, and vPTDFDCPowerFlow.

DCPowerFlow(
    exporter::Union{Nothing, PowerFlowEvaluationModel} = nothing,
)

An evaluation model for a standard DC powerflow.

This provides a fast approximate solution to the AC powerflow problem, by solving for the bus voltage angles under some simplifying assumptions (lossless lines, constant voltage magnitudes, etc.). For details, see Wikipedia or section 4 of the MATPOWER docs. If not nothing, the exporter should be a PSSEExportPowerFlow.

LevenbergMarquardtACPowerFlow <: ACPowerFlowSolverType

An ACPowerFlowSolverType corresponding to the Levenberg-Marquardt iterative method.

NewtonRaphsonACPowerFlow <: ACPowerFlowSolverType

An ACPowerFlowSolverType corresponding to a basic Newton-Raphson iterative method. The Newton step is taken verbatim at each iteration: no line search is performed.

PTDFDCPowerFlow(
    exporter::Union{Nothing, PowerFlowEvaluationModel} = nothing,
)

An evaluation model that calculates line flows using the Power Transfer Distribution Factor Matrix.

This approximates the branch flows in the power grid, under some simplifying assumptions (lossless lines, constant voltage magnitudes, etc.). See section 4 of the MATPOWER docs for details. If not nothing, the exporter should be a PSSEExportPowerFlow.

An abstract supertype for all types of power flows. Subtypes: ACPowerFlow, AbstractDCPowerFlow, and PSSEExportPowerFlow. The last isn't a power flow in the usual sense, but it is implemented that way (with writing the export file as solving the power flow) for interface reasons.

RobustHomotopyPowerFlow <: ACPowerFlowSolverType

An ACPowerFlowSolverType corresponding to a homotopy iterative method, based on the paper "Improving the robustness of Newton-based power flow methods to cope with poor initial points".

TrustRegionACPowerFlow <: ACPowerFlowSolverType

An ACPowerFlowSolverType corresponding to the Powell dogleg iterative method.

vPTDFDCPowerFlow(
    exporter::Union{Nothing, PowerFlowEvaluationModel} = nothing,
)

An evaluation model that calculates line flows using a virtual Power Transfer Distribution Factor Matrix.

This is a replacement for the PTDFDCPowerFlow for large grids, where creating and storing the full PTDF matrix would be infeasible or slow. See the PowerNetworkMatrices.jl docs for details. If not nothing, the exporter should be a PSSEExportPowerFlow.

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.

Note that data must have been created from the System sys using one of the PowerFlowData constructors.

Example

using PowerFlows, PowerSystemCaseBuilder
sys = build_system(PSITestSystems, "c_sys14")
data = PowerFlowData(PTDFDCPowerFlow(), sys, time_steps = 2)
d = solve_powerflow(data, sys)
display(d["2"]["flow_results"])

solve_powerflow(
    ::T,
    sys::PSY.System;
) where T <: AbstractDCPowerFlow

Evaluates the provided DC power flow method T on the PowerSystems.System sys, returning a dictionary of DataFrames containing the calculated branch flows and bus angles.

Provided for convenience: this interface bypasses the need to create a PowerFlowData struct, but that's still what's happening under the hood.

Example

using PowerFlows, PowerSystemCaseBuilder
sys = build_system(PSITestSystems, "c_sys5")
d = solve_powerflow(DCPowerFlow(), sys)
display(d["1"]["flow_results"])
display(d["1"]["bus_results"])

solve_and_store_power_flow!(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.
• system::PSY.System: The power system model, a PowerSystems.System struct.
• kwargs...: Additional keyword arguments.

Keyword Arguments

• 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_and_store_power_flow!(pf, sys)

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

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

Similar to solve_and_store_power_flow! but does not update the system struct with results. Returns the results in a dictionary of dataframes.

Examples

res = solve_powerflow(pf, sys)

PSSEExportPowerFlow(psse_version::Symbol, export_dir::AbstractString; kwargs...)

An evaluation model for exporting power flow results to PSSE format.

Arguments:

• psse_version::Symbol: The version of PSSE to export to. Must be among [:v33, :v35].
• export_dir::AbstractString: The directory where the PSSE files will be exported.

Optional keyword arguments:

• name::AbstractString: The base name for the exported files. Defaults to "export".
• write_comments::Bool: Whether to write comments in the exported files. Defaults to false.
• overwrite::Bool: Whether to overwrite the file if it exists already. Defaults to false.

Structure to perform an export from a Sienna System, plus optional updates from PowerFlowData, to the PSS/E format.

Construct this object 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 [:v33, :v35]
• 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

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

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 constructed.

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.