Basic Data Utilities
By default PowerModels uses a data model that captures the bulk of the features of realistic transmission network datasets such as, inactive devices, breakers and HVDC lines. However, these features preclude popular matrix-based analysis of power network datasets such as incidence, admittance, and power transfer distribution factor (PTDF) matrices. To support these types of analysis PowerModels introduces the concept of a basic networks, which are network datasets that satisfy the properties required to interpret the system in a matrix form.
make_basic_network is provided to ensure that a given network dataset satisfies the properties required for a matrix interpretation (the specific requirements are outlined in the function documentation block). If the given dataset does not satisfy the properties,
make_basic_network transforms the dataset to enforce them.
given a powermodels data dict produces a new data dict that conforms to the following basic network model requirements.
- no dclines
- no switches
- no inactive components
- all components are numbered from 1-to-n
- the network forms a single connected component
- there exactly one phase angle reference bus
- generation cost functions are quadratic
- all branches have explicit thermal limits
- phase shift on all transformers is set to 0.0
- bus shunts have 0.0 conductance values
users requiring any of the features listed above for their analysis should use the non-basic PowerModels routines.
The standard procedure for loading basic network data is as follows,
data = make_basic_network(parse_file("<path to network data file>"))
modifications to the original network data file are indicated by logging messages in the terminal.
make_basic_network results in significant changes to a dataset,
export_file can be used to inspect and modify the new derivative dataset that conforms to the basic network requirements.
Using a basic network dataset the following functions can be used to extract key power system quantities in vectors and matrix forms. The prefix
_basic_ distinguishes these functions from similar tools that operate on any type of PowerModels data, including those that are not amenable to a vector/matrix format.
given a basic network data dict, returns a complex valued vector of bus voltage values in rectangular coordinates as they appear in the network data.
given a basic network data dict, returns a complex valued vector of bus power injections as they appear in the network data.
given a basic network data dict, returns a complex valued vector of branch series impedances.
given a basic network data dict, returns a sparse integer valued incidence matrix with one row for each branch and one column for each bus in the network. In each branch row a +1 is used to indicate the from bus and -1 is used to indicate to bus.
given a basic network data dict, returns a sparse complex valued admittance matrix with one row and column for each bus in the network.
given a basic network data dict, returns a sparse real valued susceptance matrix with one row and column for each bus in the network. This susceptance matrix reflects the imaginary part of an admittance matrix that only considers the branch series impedance.
given a basic network data dict, returns a sparse real valued branch susceptance matrix with one row for each branch and one column for each bus in the network. Multiplying the branch susceptance matrix by bus phase angels yields a vector active power flow values for each branch.
given a basic network data dict, returns a sparse real valued Jacobian matrix of the ac power flow problem. The power variables are ordered by p and then q while voltage values are ordered by voltage angle and then voltage magnitude.
given a basic network data dict, returns a real valued ptdf matrix with one row for each branch and one column for each bus in the network. Multiplying the ptdf matrix by bus injection values yields a vector active power flow values on each branch.
given a basic network data dict and a branch index returns a row of the ptdf matrix reflecting that branch.
Several variants of the real-valued susceptance matrix are possible. PowerModels uses the version based on inverse of branch series impedance, that is
imag(inv(r + x im)). One may observe slightly different results when compared to tools that use other variants such as
Matrix-based network data can be combined to compute a number of useful quantities. For example, by combining the incidence matrix and the series impedance one can drive the susceptance and branch susceptance matrices as follows,
import LinearAlgebra: Diagonal bz = calc_basic_branch_series_impedance(data) A = calc_basic_incidence_matrix(data) Y = imag(Diagonal(inv.(bz))) B = A'*Y*A # equivalent to calc_basic_susceptance_matrix BB = (A'*Y)' # equivalent to calc_basic_branch_susceptance_matrix
The bus voltage angles can be combined with the susceptance and branch susceptance matrices to observe how power flows through the network as follows,
va = angle.(calc_basic_bus_voltage(data)) B = calc_basic_susceptance_matrix(data) BB = calc_basic_branch_susceptance_matrix(data) bus_injection = -B * va branch_power = -BB * va
In the inverse operation, bus injection values can be combined with a PTDF matrix to compute branch flow values as follows,
bi = real(calc_basic_bus_injection(data)) PTDF = calc_basic_ptdf_matrix(data) branch_power = PTDF * bi
Finally, the following function provides a tool to solve a DC power flow on basic network data using Julia's native linear equation solver,
given a basic network data dict, computes real valued vector of bus voltage phase angles by solving a dc power flow.
By default PowerModels uses Julia's SparseArrays to ensure the best performance of matrix operations on large power network datasets. The function
Matrix(sparse_array) can be used to covert a sparse matrix into a full matrix when that is preferred.