PowerFlows

ACPowerFlow{ACSolver}(; kwargs...) where {ACSolver <: ACPowerFlowSolverType}
ACPowerFlow(; kwargs...)

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

Arguments

• ACSolver: The type of AC power flow solver to use, which must be a subtype of ACPowerFlowSolverType. If not specified, defaults to 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. Default is nothing.
• calculate_loss_factors::Bool: Whether to calculate loss factors during the power flow solution. Default is false.
• calculate_voltage_stability_factors::Bool: Whether to calculate voltage stability factors. Default is false.
• generator_slack_participation_factors: 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{Tuple{DataType, String}, Float64}, it should map (component_type, component_name) tuples to participation factors. If a Vector of such dictionaries, different participation factors can be used for different time steps. Default is nothing.
• enhanced_flat_start::Bool: Whether to use enhanced flat start initialization. Default is true.
• robust_power_flow::Bool: Whether to use run a DC power flow as a fallback if the initial residual is large. Default is false.
• skip_redistribution::Bool: Whether to skip slack redistribution. Default is false.
• network_reductions::Vector{PNM.NetworkReduction}: Network reductions to apply. Default is an empty vector.
• time_steps::Int: Number of time steps to solve. Default is 1.
• time_step_names::Vector{String}: Names for each time step. Default is an empty vector.
• correct_bustypes::Bool: Whether to automatically correct bus types based on available generation. Default is false.
• solver_settings::Dict{Symbol, Any}: Additional keyword arguments to pass to the solver. Default is an empty dictionary.

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 power flow 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.

See also: ACPowerFlow.

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

DCPowerFlow(; kwargs...)

An evaluation model for a standard DC power flow.

This provides a fast approximate solution to the AC power flow problem, by solving for the bus voltage angles under some simplifying assumptions (lossless lines, constant voltage magnitudes, etc.). Branch flows are then calculated from the voltage angles. For details, see Wikipedia or section 4 of the MATPOWER docs.

Arguments

• exporter::Union{Nothing, PowerFlowEvaluationModel}: An optional exporter for the power flow results. If not nothing, it should be a PSSEExportPowerFlow. Default is nothing.
• network_reductions::Vector{PNM.NetworkReduction}: Network reductions to apply. Default is an empty vector.
• time_steps::Int: Number of time steps to solve. Default is 1.
• time_step_names::Vector{String}: Names for each time step. Default is an empty vector.
• correct_bustypes::Bool: Whether to automatically correct bus types based on available generation. Default is false.

LevenbergMarquardtACPowerFlow <: ACPowerFlowSolverType

An ACPowerFlowSolverType corresponding to the Levenberg-Marquardt iterative method. This is more robust than the basic Newton-Raphson method, but also more computationally intensive. Due to the difficulty of tuning meta parameters, this method may occasionally fail to converge where other methods would succeed.

See also: ACPowerFlow.

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.

See also: ACPowerFlow.

PTDFDCPowerFlow(; kwargs...)

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.). In contrast to DCPowerFlow, branch flows are computed directly from bus power injections, without use of the voltage angles. See section 4 of the MATPOWER docs for details.

Arguments

• exporter::Union{Nothing, PowerFlowEvaluationModel}: An optional exporter for the power flow results. If not nothing, it should be a PSSEExportPowerFlow. Default is nothing.
• network_reductions::Vector{PNM.NetworkReduction}: Network reductions to apply. Default is an empty vector.
• time_steps::Int: Number of time steps to solve. Default is 1.
• time_step_names::Vector{String}: Names for each time step. Default is an empty vector.
• correct_bustypes::Bool: Whether to automatically correct bus types based on available generation. Default is false.

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". This is significantly more robust than Newton-Raphson, but also slower by an order of magnitude or two.

See also: ACPowerFlow.

TrustRegionACPowerFlow <: ACPowerFlowSolverType

An ACPowerFlowSolverType corresponding to the Powell dogleg iterative method. This is a bit more robust than the basic Newton-Raphson method and comparably lightweight.

See also: ACPowerFlow.

vPTDFDCPowerFlow(; kwargs...)

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.

Arguments

• exporter::Union{Nothing, PowerFlowEvaluationModel}: An optional exporter for the power flow results. If not nothing, it should be a PSSEExportPowerFlow. Default is nothing.
• network_reductions::Vector{PNM.NetworkReduction}: Network reductions to apply. Default is an empty vector.
• time_steps::Int: Number of time steps to solve. Default is 1.
• time_step_names::Vector{String}: Names for each time step. Default is an empty vector.
• correct_bustypes::Bool: Whether to automatically correct bus types based on available generation. Default is false.

FlowReporting

Enumeration describing the type of flows reported in power flow results.

Values

• ARC_FLOWS = 0: Report total flows corresponding to arcs.
• BRANCH_FLOWS = 1: Report flows for individual branches.

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 flows and bus voltages for the input PSY.System at that timestep. The flowreporting input determines if flows are reported for arcs (FlowReporting.ARCFLOWS) or for branches (FlowReporting.BRANCHFLOWS)

Arguments:

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

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(; time_steps = 2), sys)
d = solve_power_flow(data, sys)
display(d["2"]["flow_results"])

solve_power_flow(
    pf::T,
    sys::PSY.System,
    flow_reporting::FlowReporting
) where T <: AbstractDCPowerFlow

Evaluates the provided DC power flow method pf on the PowerSystems.System sys, returning a dictionary of DataFrames containing the calculated flows and bus angles. The flowreporting input determines if flows are reported for arcs (FlowReporting.ARCFLOWS) or for branches (FlowReporting.BRANCH_FLOWS)

Configuration options like time_steps, time_step_names, network_reductions, and correct_bustypes should be set on the power flow object (e.g., DCPowerFlow(; time_steps=2)).

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_power_flow(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).

Configuration options like time_steps, time_step_names, network_reductions, and correct_bustypes should be set on the ACPowerFlow object.

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

Arguments

• pf::ACPowerFlow{<:ACPowerFlowSolverType}: the power flow struct, which contains configuration options.
• system::PSY.System: The power system model, a PowerSystems.System struct.
• kwargs...: Additional keyword arguments passed to the solver.

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)

# With correct_bustypes enabled
pf = ACPowerFlow(; correct_bustypes = true)
solve_and_store_power_flow!(pf, sys)

# Passing solver 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_power_flow(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.