Quick Start Guide

Note

PowerSystemCaseBuilder.jl is a helper library that makes it easier to reproduce examples in the documentation and tutorials. Normally you would pass your local files to create the system data instead of calling the function build_system. For more details visit PowerSystemCaseBuilder Documentation

For more details about loading data and adding more dynamic components check the Creating a System with Dynamic devices section of the documentation in PowerSystems.jl.

Loading data

Data can be loaded from a pss/e raw file and a pss/e dyr file.

julia> using PowerNetworkMatrices
julia> using PowerSystemCaseBuilder
julia> import PowerNetworkMatrices as PNM
julia> import PowerSystemCaseBuilder as PSB
julia> sys = PSB.build_system(PSB.PSITestSystems, "c_sys5")┌ Info: Building new system c_sys5 from raw data
└   sys_descriptor.raw_data = "/home/runner/.julia/artifacts/edcb5940e84a802a86ad4f2223214d33121ac044/PowerSystemsTestData-4.0.2/psy_data/data_5bus_pu.jl"
[ Info: Serialized time series data to /home/runner/.julia/packages/PowerSystemCaseBuilder/zW01F/data/serialized_system/8584b9e729c8aa68ee5405660c6258cde1f67ed3b68f114823707912e9a0d16c/c_sys5_time_series_storage.h5.
[ Info: Serialized System to /home/runner/.julia/packages/PowerSystemCaseBuilder/zW01F/data/serialized_system/8584b9e729c8aa68ee5405660c6258cde1f67ed3b68f114823707912e9a0d16c/c_sys5.json
[ Info: Serialized System metadata to /home/runner/.julia/packages/PowerSystemCaseBuilder/zW01F/data/serialized_system/8584b9e729c8aa68ee5405660c6258cde1f67ed3b68f114823707912e9a0d16c/c_sys5_metadata.json
              System
┌───────────────────┬─────────────┐
│ Property          │ Value       │
├───────────────────┼─────────────┤
│ Name              │             │
│ Description       │             │
│ System Units Base │ SYSTEM_BASE │
│ Base Power        │ 100.0       │
│ Base Frequency    │ 60.0        │
│ Num Components    │ 25          │
└───────────────────┴─────────────┘

     Static Components
┌─────────────────┬───────┐
│ Type            │ Count │
├─────────────────┼───────┤
│ ACBus           │ 5     │
│ Arc             │ 6     │
│ Line            │ 6     │
│ PowerLoad       │ 3     │
│ ThermalStandard │ 5     │
└─────────────────┴───────┘

                                Forecast Summary
┌────────────┬────────────────┬──────────────────┬──────────────────┬───────────
│ owner_type │ owner_category │ name             │ time_series_type │ initial_ ⋯
│ String     │ String         │ String           │ String           │ String   ⋯
├────────────┼────────────────┼──────────────────┼──────────────────┼───────────
│ PowerLoad  │ Component      │ max_active_power │ Deterministic    │ 2024-01- ⋯
└────────────┴────────────────┴──────────────────┴──────────────────┴───────────
                                                               6 columns omitted

Computation of the PTDF matrix

Once system data is loaded, network matrices can be evaluated. The following example shows how the PTDF matrix is computed.

The function PTDF is called for the evaluation of the matrix and other data. These are stored in a structure of type PTDF.

julia> # evaluate the PTDF structure containing the matrix and other data.
       ptdf_matrix = PNM.PTDF(sys);[ Info: Finding subnetworks via iterative union find
julia> # show the PTDF matrix.
       PNM.get_data(ptdf_matrix)5×6 Matrix{Float64}:
 -0.368495   0.193917  0.193917  0.437588   0.193917   0.368495
 -0.217552  -0.475895  0.524105  0.258343   0.524105   0.217552
 -0.159538  -0.348989  0.651011  0.189451  -0.348989   0.159538
  0.0        0.0       0.0       0.0        0.0        0.0
 -0.480452   0.159538  0.159538  0.36001    0.159538  -0.519548

As it can be seen, the PTDF matrix is stored internally in transposed form for computational efficiency. The function get_ptdf_data returns the data in the standard orientation (arcs × buses).

The matrix axes are indexed by arc tuples (from_bus_number, to_bus_number) and bus numbers. You can inspect the axes and lookup dictionaries as follows:

julia> # axes and lookup dictionaries describe the arc tuples and bus numbers for each dimension
       PNM.get_axes(ptdf_matrix)([1, 2, 3, 4, 5], [(4, 5), (1, 2), (3, 4), (1, 4), (2, 3), (1, 5)])
julia> PNM.get_lookup(ptdf_matrix)(Dict(5 => 5, 4 => 4, 2 => 2, 3 => 3, 1 => 1), Dict((4, 5) => 1, (1, 2) => 2, (3, 4) => 3, (1, 4) => 4, (2, 3) => 5, (1, 5) => 6))

Elements can be accessed using arc tuples and bus numbers directly. The example below picks the first arc and first bus from the matrix axes so it works for any system:

julia> some_arc = PNM.get_axes(ptdf_matrix)[2][1](4, 5)
julia> some_bus = PNM.get_axes(ptdf_matrix)[1][1]1
julia> ptdf_matrix[some_arc, some_bus]-0.36849525887737133