Given a vector of Sienna bus numbers, create a dictionary from Sienna bus number to PSS/E-compatible bus number. Assumes that the Sienna bus numbers are positive and unique. Guarantees determinism: if the input contains the same bus numbers in the same order, the output will. Guarantees minimal changes: that if an existing bus number is compliant, it will not be changed.
Given a vector of Sienna transformer names, create a dictionary from Sienna transformer name to PSS/E-compatible transformer name. Guarantees determinism and minimal changes.
WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Transformer Data
Given a vector of component names and a corresponding vector of container IDs (e.g., bus numbers), create unique-per-container PSS/E-compatible IDs, output a dictionary from (container ID, component name) to PSS/E-compatible component ID. The "singlesto1" flag detects components that are the only one on their bus and gives them the name "1".
Modify the values in the given System to correspond to the given PowerFlowData such that if a new PowerFlowData is constructed from the resulting system it is the same as data. See also write_powerflow_solution!. NOTE that this assumes that data was initialized from sys and then solved with no further modifications.
WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Bus Data. Sienna voltage limits treated as PSS/E normal voltage limits; PSSE emergency voltage limits left as default.
Given a vector of Sienna bus numbers, create a dictionary from Sienna bus number to PSS/E-compatible bus number. Assumes that the Sienna bus numbers are positive and unique. Guarantees determinism: if the input contains the same bus numbers in the same order, the output will. Guarantees minimal changes: that if an existing bus number is compliant, it will not be changed.
Given a vector of Sienna transformer names, create a dictionary from Sienna transformer name to PSS/E-compatible transformer name. Guarantees determinism and minimal changes.
WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Transformer Data
Given a vector of component names and a corresponding vector of container IDs (e.g., bus numbers), create unique-per-container PSS/E-compatible IDs, output a dictionary from (container ID, component name) to PSS/E-compatible component ID. The "singlesto1" flag detects components that are the only one on their bus and gives them the name "1".
Modify the values in the given System to correspond to the given PowerFlowData such that if a new PowerFlowData is constructed from the resulting system it is the same as data. See also write_powerflow_solution!. NOTE that this assumes that data was initialized from sys and then solved with no further modifications.
WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Bus Data. Sienna voltage limits treated as PSS/E normal voltage limits; PSSE emergency voltage limits left as default.
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.
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::Union{Nothing, Integer, Tuple{Vararg{Integer}}} = nothing: optional step number or tuple of step numbers (e.g., step and timestamp within step) to append to the base export name. User is responsible for updating the step.
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[].
Solves a the power flow into the system and writes the solution into the relevant structs. Updates generators active and reactive power setpoints and branches active and reactive power flows (calculated in the From - To direction) (see flow_val)
Supports passing NLsolve kwargs in the args. By default shows the solver trace.
Arguments available for nlsolve:
get_connectivity::Bool: Checks if the network is connected. Default true
method : See NLSolve.jl documentation for available solvers
xtol: norm difference in x between two successive iterates under which convergence is declared. Default: 0.0.
ftol: infinite norm of residuals under which convergence is declared. Default: 1e-8.
iterations: maximum number of iterations. Default: 1_000.
store_trace: should a trace of the optimization algorithm's state be stored? Default: false.
show_trace: should a trace of the optimization algorithm's state be shown on STDOUT? Default: false.
extended_trace: should additifonal algorithm internals be added to the state trace? Default: false.
Examples
solve_ac_powerflow!(sys)
+Public API Reference · PowerFlows.jl
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.
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::Union{Nothing, Integer, Tuple{Vararg{Integer}}} = nothing: optional step number or tuple of step numbers (e.g., step and timestamp within step) to append to the base export name. User is responsible for updating the step.
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[].
Solves a the power flow into the system and writes the solution into the relevant structs. Updates generators active and reactive power setpoints and branches active and reactive power flows (calculated in the From - To direction) (see flow_val)
Supports passing NLsolve kwargs in the args. By default shows the solver trace.
Arguments available for nlsolve:
get_connectivity::Bool: Checks if the network is connected. Default true
method : See NLSolve.jl documentation for available solvers
xtol: norm difference in x between two successive iterates under which convergence is declared. Default: 0.0.
ftol: infinite norm of residuals under which convergence is declared. Default: 1e-8.
iterations: maximum number of iterations. Default: 1_000.
store_trace: should a trace of the optimization algorithm's state be stored? Default: false.
show_trace: should a trace of the optimization algorithm's state be shown on STDOUT? Default: false.
extended_trace: should additifonal algorithm internals be added to the state trace? Default: false.
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.
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.
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.
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.
In order to contribute to PowerSimulationsDynamics.jl repository please read the following sections of InfrastructureSystems.jl documentation in detail:
In order to contribute to PowerSimulationsDynamics.jl repository please read the following sections of InfrastructureSystems.jl documentation in detail:
The latest stable release of PowerFlows can be installed using the Julia package manager with
] add PowerFlows
For the current development version, "checkout" this package with
] add PowerFlows#main
PowerFlows has been developed as part of the Scalable Integrated Infrastructure Planning (SIIP) initiative at the U.S. Department of Energy's National Renewable Energy Laboratory (NREL)
Settings
This document was generated with Documenter.jl version 0.27.25 on Thursday 16 January 2025. Using Julia version 1.11.2.
The latest stable release of PowerFlows can be installed using the Julia package manager with
] add PowerFlows
For the current development version, "checkout" this package with
] add PowerFlows#main
PowerFlows has been developed as part of the Scalable Integrated Infrastructure Planning (SIIP) initiative at the U.S. Department of Energy's National Renewable Energy Laboratory (NREL)
Settings
This document was generated with Documenter.jl version 0.27.25 on Thursday 16 January 2025. Using Julia version 1.11.2.