Internal

struct ACPowerFlowJacobian

A struct that represents the Jacobian matrix for AC power flow calculations.

This struct uses the functor pattern, meaning instances of ACPowerFlowJacobian store the data (Jacobian matrix) internally and can be called as a function at the same time. Calling the instance as a function updates the stored Jacobian matrix.

Fields

• data::ACPowerFlowData: The grid model data used for power flow calculations.
• Jf!::Function: A function that calculates the Jacobian matrix inplace.
• Jv::SparseArrays.SparseMatrixCSC{Float64, Int32}: The Jacobian matrix, which is updated by the function Jf!.

(J::ACPowerFlowJacobian)(time_step::Int64)

Update the Jacobian matrix Jv using the function Jf! and the provided data and time step.

Defining this method allows an instance of ACPowerFlowJacobian to be called as a function, following the functor pattern.

Arguments

• time_step::Int64: The time step for the calculations.

Example

J = ACPowerFlowJacobian(data, time_step)
J(time_step)  # Updates the Jacobian matrix Jv

ACPowerFlowJacobian(data::ACPowerFlowData, time_step::Int64) -> ACPowerFlowJacobian

This is the constructor for ACPowerFlowJacobian. Create an ACPowerFlowJacobian instance. As soon as the instance is created, it already has the Jacobian matrix structure initialized and its values updated, stored internally as Jv. The data instance is stored internally and used to update the Jacobian matrix because the structure of the Jacobian matrix is tied to the data. Changing the data requires creating a new instance of ACPowerFlowJacobian.

Arguments

• data::ACPowerFlowData: The data used for power flow calculations.
• time_step::Int64: The time step for the calculations.

Returns

• ACPowerFlowJacobian: An instance of ACPowerFlowJacobian.

#Example

J = ACPowerFlowJacobian(data, time_step)  # Creates an instance J of ACPowerFlowJacobian, with the Jacobian matrix stored internally as J.Jv initialized and updated.
J(time_step)  # Updates the Jacobian matrix stored internally in J (J.Jv) with the latest state of the `data` (`ACPowerFlowData` instance) and the provided time step.
J.Jv  # Access the Jacobian matrix stored internally in J.

(J::ACPowerFlowJacobian)(J::SparseArrays.SparseMatrixCSC{Float64, Int32}, time_step::Int64)

Use the ACPowerFlowJacobian to update the provided Jacobian matrix J inplace.

Update the internally stored Jacobian matrix Jv using the function Jf! and the provided data and time step, and write the updated Jacobian values to J.

This method allows an instance of ACPowerFlowJacobian to be called as a function, following the functor pattern.

Arguments

• J::SparseArrays.SparseMatrixCSC{Float64, Int32}`: A sparse matrix to be updated with new values of the Jacobian matrix.
• time_step::Int64: The time step for the calculations.

Example

J = ACPowerFlowJacobian(data, time_step)
Jv = SparseArrays.sparse(Float64[], Int32[], Int32[])
J(Jv, time_step)  # Updates the Jacobian matrix Jv and writes it to J

struct ACPowerFlowResidual

A struct to keep track of the residuals in the Newton-Raphson AC power flow calculation.

Fields

• data::ACPowerFlowData: The grid model data.
• Rf!::Function: A function that updates the residuals based on the latest values stored in the grid at the given iteration.
• Rv::Vector{Float64}: A vector of the values of the residuals.
• P_net::Vector{Float64}: A vector of net active power injections.
• Q_net::Vector{Float64}: A vector of net reactive power injections.

ACPowerFlowResidual(data::ACPowerFlowData, time_step::Int64)

Create an instance of ACPowerFlowResidual for a given time step.

Arguments

• data::ACPowerFlowData: The power flow data representing the power system model.
• time_step::Int64: The time step for which the power flow calculation is executed.

Returns

• ACPowerFlowResidual: An instance containing the residual values, net bus active power injections,

and net bus reactive power injections.

(Residual::ACPowerFlowResidual)(x::Vector{Float64}, time_step::Int64)

Update the AC power flow residuals inplace and store the result in the attribute Rv of the struct. The inputs are the values of state vector x and the current time step time_step. This function implements the functor approach for the ACPowerFlowResidual struct. This makes the struct callable. Calling the ACPowerFlowResidual will also update the values of P, Q, V, Θ in the data struct.

Arguments

• x::Vector{Float64}: The state vector values.
• time_step::Int64: The current time step.

(Residual::ACPowerFlowResidual)(Rv::Vector{Float64}, x::Vector{Float64}, time_step::Int64)

Evaluate the AC power flow residuals and store the result in Rv using the provided state vector x and the current time step time_step. The residuals are updated inplace in the struct and additionally copied to the provided array. This function implements the functor approach for the ACPowerFlowResidual struct. This makes the struct callable. Calling the ACPowerFlowResidual will also update the values of P, Q, V, Θ in the data struct.

Arguments

• Rv::Vector{Float64}: The vector to store the calculated residuals.
• x::Vector{Float64}: The state vector.
• time_step::Int64: The current time step.

A cached linear solver using KLU. Carefully written so as to minimize allocations: solve! and numeric_refactor! are completely non-allocating.

Fields:

• K: the underlying KLU object.
• reuse_symbolic::Bool: reuse the symbolic factorization. Defaults to true.
• check_pattern::Bool: if true, numeric_refactor! verifies that the new

matrix has the same sparsity structure. Defaults to true. -rf_common, rf_symbolic, rf_numeric: internal usage. Stored to avoid allocations.

Constructor.

Abstract supertype for all cached linear solvers. Subtypes must implement: symbolic_factor!, symbolic_refactor!, numeric_refactor! (which doubles as numeric_factor!), and solve!.

Cache for non-linear methods

Fields

-x::Vector{Float64}: the current state vector. -r::Vector{Float64}: the current residual. -Δx_nr::Vector{Float64}: the step under the Newton-Raphson method. The remainder of the fields are only used in the TrustRegionACPowerFlow: -r_predict::Vector{Float64}: the predicted residual at x+Δx_proposed, under a linear approximation: i.e J_x⋅(x+Δx_proposed). -Δx_proposed::Vector{Float64}: the suggested step Δx, selected among Δx_nr, Δx_cauchy, and the dogleg interpolation between the two. The first is chosen when x+Δx_nr is inside the trust region, the second when both x+Δx_cauchy and x+Δx_nr are outside the trust region, and the third when x+Δx_cauchy is inside and x+Δx_nr outside. The dogleg step selects the point where the line from x+Δx_cauchy to x+Δx_nr crosses the boundary of the trust region. -Δx_cauchy::Vector{Float64}: the step to the Cauchy point if the Cauchy point lies within the trust region, otherwise a step in that direction.

A PowerFlowContainer that represents its data as a PSY.System

_create_jacobian_matrix_structure(data::ACPowerFlowData, time_step::Int64) -> SparseMatrixCSC{Float64, Int32}

Create the structure of the Jacobian matrix for an AC power flow problem. Inputs are the grid model as an instance of ACPowerFlowData at a given time step.

Arguments

• data::ACPowerFlowData: The power flow model.
• time_step::Int64: The specific time step for which the Jacobian matrix structure is created.

Returns

• SparseMatrixCSC{Float64, Int32}: A sparse matrix with structural zeros representing the structure of the Jacobian matrix.

Description

This function initializes the structure of the Jacobian matrix for an AC power flow problem. The Jacobian matrix is used in power flow analysis to represent the partial derivatives of bus active and reactive power injections with respect to bus voltage magnitudes and angles.

Unlike some commonly used approaches where the Jacobian matrix is constructed as four submatrices, each grouping values for the four types of partial derivatives, this function groups the partial derivatives by bus. The structure is organized as groups of 4 values per bus. See the example below for details.

This approach is more memory-efficient. Furthermore, this structure results in a more efficient factorization because the values are more likely to be grouped close to the diagonal. Refer to Electric Energy Systems: Analysis and Operation by Antonio Gomez-Exposito and Fernando L. Alvarado for more details.

The function initializes three arrays (rows, columns, and values) to store the row indices, column indices, and values of the non-zero elements of the Jacobian matrix, respectively.

For each bus in the system, the function iterates over its neighboring buses and determines the type of each neighboring bus (REF, PV, or PQ). Depending on the bus type, the function adds the appropriate entries to the Jacobian matrix structure.

• For REF buses, entries are added for local active and reactive power.
• For PV buses, entries are added for active and reactive power with respect to angle, and for local reactive power.
• For PQ buses, entries are added for active and reactive power with respect to voltage magnitude and angle.

For example, suppose we have a system with 3 buses: bus 1 is REF, bus 2 is PV, and bus 3 is PQ. Let ΔPⱼ, ΔQⱼ be the active, reactive power balance at the jth bus. Let Pⱼ and Qⱼ be the active and reactive power generated at the jth bus (REF and PV only). Then the state vector is [P₁, Q₁, Q₂, θ₂, V₃, θ₃], and the Jacobian matrix is

| ∂ΔP₁/∂P₁ | ∂ΔP₁/∂Q₁ | ∂ΔP₁/∂Q₂ | ∂ΔP₁/∂θ₂ | ∂ΔP₁/∂V₃ | ∂ΔP₁/∂θ₃ | | ∂ΔQ₁/∂P₁ | ∂ΔQ₁/∂Q₁ | ∂ΔQ₁/∂Q₂ | ∂ΔQ₁/∂θ₂ | ∂ΔQ₁/∂V₃ | ∂ΔQ₁/∂θ₃ | | ∂ΔP₂/∂P₁ | ∂ΔP₂/∂Q₁ | ∂ΔP₂/∂Q₂ | ∂ΔP₂/∂θ₂ | ∂ΔP₂/∂V₃ | ∂ΔP₂/∂θ₃ | | ∂ΔQ₂/∂P₁ | ∂ΔQ₂/∂Q₁ | ∂ΔQ₂/∂Q₂ | ∂ΔQ₂/∂θ₂ | ∂ΔQ₂/∂V₃ | ∂ΔQ₂/∂θ₃ | | ∂ΔP₃/∂P₁ | ∂ΔP₃/∂Q₁ | ∂ΔP₃/∂Q₂ | ∂ΔP₃/∂θ₂ | ∂ΔP₃/∂V₃ | ∂ΔP₃/∂θ₃ | | ∂ΔQ₃/∂P₁ | ∂ΔQ₃/∂Q₁ | ∂ΔQ₃/∂Q₂ | ∂ΔQ₃/∂θ₂ | ∂ΔQ₃/∂V₃ | ∂ΔQ₃/∂θ₃ |

In reality, for large networks, this matrix would be sparse, and each 4x4 block would only be nonzero when there's a line between the respective buses.

Finally, the function constructs a sparse matrix from the collected indices and values and returns it.

Create the Jacobian matrix structure for a PV bus. Ignoring this because we fill all four values even for PV buses with structural zeros using the same function as for PQ buses.

Create the Jacobian matrix structure for a reference bus (REF). Ignoring this because we fill all four values even for PV buses with structiural zeros using the same function as for PQ buses.

Create the Jacobian matrix structure for a PQ bus. Using this for all buses because a) for REF buses it doesn't matter if there are 2 values or 4 values - there are not many of them in the grid b) for PV buses we fill all four values because we can have a PV -> PQ transition and then we need to fill all four values

When solving AC power flows, if the initial guess has large residual, we run a DC power flow as a fallback. This runs a DC powerflow on data::ACPowerFlowData for the given time_step, and writes the solution to data.bus_angles.

Check error and do refinement.

Sets Δx_proposed equal to the Δx by which we should update x. Decides between the Cauchy step Δx_cauchy, Newton-Raphson step Δx_nr, and the dogleg interpolation between the two, based on which fall within the trust region.

Try to make an informative one or two character name for the load/generator/etc.

• "generator-1234-AB" -> "AB"
• "123CT7" -> "7"
• "load1234" -> "34"

Obtain total load on bus b

Validate that the Sienna area/zone names parse as PSS/E-compatible area/zone numbers, output a mapping

Given a vector of Sienna bus names, create a dictionary from Sienna bus name to PSS/E-compatible bus name. Guarantees determinism and minimal changes.

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Bus Data

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.

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Bus Data

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

Runs the full NewtonRaphsonACPowerFlow.

Keyword arguments:

• maxIterations::Int: maximum iterations. Default: 30.
• tol::Float64: tolerance. The iterative search ends when norm(abs.(residual)) < tol. Default: 1.0e-9.
• refinement_threshold::Float64: If the solution to J_x Δx = r satisfies norm(J_x Δx - r, 1)/norm(r, 1) > refinement_threshold, do iterative refinement to improve the accuracy. Default: 0.05.
• refinement_eps::Float64: run iterative refinement on J_x Δx = r until norm(Δx_{i}-Δx_{i+1}, 1)/norm(r,1) < refinement_eps. Default: 1.0e-6

Runs the full TrustRegionNRMethod.

Keyword arguments:

• maxIterations::Int: maximum iterations. Default: 30.
• tol::Float64: tolerance. The iterative search ends when maximum(abs.(residual)) < tol. Default: 1.0e-9.
• factor::Float64: the trust region starts out with radius factor*norm(x_0, 1), where x_0 is our initial guess, taken from data. Default: 1.0.
• eta::Float64: improvement threshold. If the observed improvement in our residual exceeds eta times the predicted improvement, we accept the new x_i. Default: 0.0001.

Sets the Newton-Raphson step. Usually, this is just J.Jv \ stateVector.r, but J.Jv might be singular.

Does a single iteration of NewtonRaphsonACPowerFlow. Updates the r and x fields of the stateVector, and computes the Jacobian at the new x.

Returns a stand-in matrix for singular J's.

Solve for the Newton-Raphson step, given the factorization object for J.Jv (if non-singular) or its stand-in (if singular).

Does a single iteration of the TrustRegionNRMethod: updates the x and r fields of the stateVector and computes the value of the Jacobian at the new x, if needed. Unlike _simple_step, this has a return value, the updated value of delta`.

Updates the flow on the branches

Used to update Jv based on the bus voltages, angles, etc. in data.

_update_residual_values!(
    F::Vector{Float64},
    x::Vector{Float64},
    P_net::Vector{Float64},
    Q_net::Vector{Float64},
    data::ACPowerFlowData,
    time_step::Int64,
)

Update the residual values for the Newton-Raphson AC power flow calculation. This function is used internally in the ACPowerFlowResidual struct. This function also updates the values of P, Q, V, Θ in the data struct.

Arguments

• F::Vector{Float64}: Vector of the values of the residuals.
• x::Vector{Float64}: State vector values.
• P_net::Vector{Float64}: Vector of net active power injections at each bus.
• Q_net::Vector{Float64}: Vector of net reactive power injections at each bus.
• data::ACPowerFlowData: Data structure representing the grid model for the AC power flow calculation.
• time_step::Int64: The current time step for which the residual values are being updated.

Temporary, very specialized proof of concept patch for https://github.com/JuliaLang/julia/issues/55835

calculate_loss_factors(data::ACPowerFlowData, Jv::SparseMatrixCSC{Float64, Int32}, time_step::Int)

Calculate and store the active power loss factors in the loss_factors matrix of the ACPowerFlowData structure for a given time step.

The loss factors are computed using the Jacobian matrix Jv and the vector dSbus_dV_ref, which contains the partial derivatives of slack power with respect to bus voltages. The function interprets changes in slack active power injection as indicative of changes in grid active power losses. KLU is used to factorize the sparse Jacobian matrix to solve for the loss factors.

Arguments

• data::ACPowerFlowData: The data structure containing power flow information, including the loss_factors matrix.
• Jv::SparseMatrixCSC{Float64, Int32}: The sparse Jacobian matrix of the power flow system.
• time_step::Int: The time step index for which the loss factors are calculated.

Calculate x0 from data.

Throw a NotImplementedError if the psse_version is not :v33

If val is empty, returns T(); if not, asserts that val isa T and returns val. Has nice type checker semantics.

Examples

convert_empty(Vector{String}, [])  # -> String[]
convert_empty(Vector{String}, ["a"])  # -> ["a"]
convert_empty(Vector{String}, [2])  # -> TypeError: in typeassert, expected Vector{String}, got a value of type Vector{Int64}
Base.return_types(Base.Fix1(convert_empty, Vector{String}))  # -> [Vector{String}]

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

Expand a single PowerFlowEvaluationModel into its possibly multiple parts for separate evaluation. Namely, if pfem contains a non-nothing exporter, return [pfem, exporter], else return [pfem].

Calculates the From - To complex power flow using external data of voltages of branch of type Line

Calculates the From - To complex power flow using external data of voltages of branch of type TapTransformer

Calculates the From - To complex power flow using external data of voltages of branch of type Transformer2W

Calculates the From - To complex power flow (Flow injected at the bus) of branch of type Line

Calculates the From - To complex power flow (Flow injected at the bus) of branch of type Line

Calculates the From - To complex power flow (Flow injected at the bus) of branch of type TapTransformer

Calculates the From - To complex power flow (Flow injected at the bus) of branch of type Transformer2W

Return the active power limits that should be used in power flow calculations and PSS/E exports. Redirects to PSY.get_active_power_limits in all but special cases.

Return the reactive power limits that should be used in power flow calculations and PSS/E exports. Redirects to PSY.get_reactive_power_limits in all but special cases.

If initial residual is large, run a DC power flow and see if that gives a better starting point for angles. Return the original or the result of the DC powerflow, whichever gives the smaller residual.

Create an appropriate PowerFlowContainer for the given PowerFlowEvaluationModel and initialize it from the given PSY.System.

Arguments:

• pfem::PowerFlowEvaluationModel: power flow model to construct a container for (e.g., DCPowerFlow())
• sys::PSY.System: the system from which to initialize the power flow container
• time_steps::Int: number of time periods to consider (default is 1)
• timestep_names::Vector{String}: names of the time periods defines by the argument "time_steps". Default value is String[].
• check_connectivity::Bool: Perform connectivity check on the network matrix. Default value is true.

Similar to above: A*X where X is a matrix.

Matrix multiplication A*x. Written this way because a VirtualPTDF matrix does not store all of its entries: instead, it calculates them (or retrieves them from cache), one element or one row at a time.

Frees numeric factorization stored by cache, if non-null. If cache.check_pattern is true and the sparse matrix structure of A doesn't match the cached one, throws an error. Finally, computes the numeric factorization of A and stores that to cache.

Force all cached information (serialized metadata, component lists, etc.) to be regenerated

Take the output of create_component_ids and make it more suitable for JSON serialization

Trait signifying whether the PowerFlowContainer can represent multi-period data. Must be implemented for all concrete subtypes.

Frees up the current symbolic and numeric factorizations stored by cache, if non-null. Then computes the symbolic factorization of A and stores that to cache.

Symbolic refactor. Behavior depends on the values of cache.reuse_symbol and cache.check_pattern. There are 3 cases:

• !reuse_symbol: always refactor. Just calls symbolic_factor(cache, A).
• reuse_symbol && check_pattern: checks if the symbolic structure of A matches the cached one, and throws an error if it doesn't. This is to prevent bad input: we expected the structure to be the same, but it isn't.
• reuse_symbol && !check pattern: do nothing. Assume the structure of A matches the cached one.

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.

Updates system voltages and powers with power flow results

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.

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Case Identification Data

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Fixed Bus Shunt Data

If the exportsettings flag `sourcesasgeneratorsis set, exportPSY.Sourceinstances as PSS/E generators in addition toPSY.Generators. Same forstoragesas_generatorsandPSY.Storage`.

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Generator Data

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Load Data

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Non-Transformer Branch Data

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Q Record

Currently only supports two-winding transformers

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Transformer Data

WRITTEN TO SPEC: PSS/E 33.3 POM 5.2.1 Zone Data