PowerModels Network Data Format

The Network Data Dictionary

Internally PowerModels utilizes a dictionary to store network data. The dictionary uses strings as key values so it can be serialized to JSON for algorithmic data exchange.

The data dictionary organization and key names are designed to be consistent with the Matpower file format and should be familiar to power system researchers.

The network data dictionary structure is roughly as follows:

{
"name":<string>,
"version":"2",
"baseMVA":<float>,
"bus":{
    "1":{
        "index":<int>,
        "bus_type":<int>,
        "pd":<float>,
        "qd":<float>,
        ...
    },
    "2":{...},
    ...
},
"gen":{
    "1":{
        "index":<int>,
        "gen_bus":<int>,
        "pg":<float>,
        "qg":<float>,
        ...
    },
    "2":{...},
    ...
},
"branch":{
    "1":{
        "index":<int>,
        "f_bus":<int>,
        "t_bus":<int>,
        "br_r":<int>,
        ...
    },
    "2":{...},
    ...
}
}

The following commands can be used to explore the network data dictionary generated by a given Matpower data file,

network_data = PowerModels.parse_file("nesta_case3_lmbd.m")
display(network_data)

For a detailed list of all possible parameters refer to the specification document provided with Matpower.

Noteworthy Differences from Matpower Data Files

The PowerModels network data dictionary differs from the Matpower format in the following ways,

All PowerModels components have an index parameter, which can be used to uniquely identify that network element.
All network parameters are in per-unit and angles are in radians.
All non-transformer branches are given nominal transformer values (i.e. a tap of 1.0 and a shift of 0).
All branches have a transformer field indicating if they are a transformer or not.
Only quadratic active power generation cost functions are supported, at this time.
When present, the gencost data is incorporated into the gen data, the column names remain the same.
When present, the bus_names data is incorporated into the bus data under the property "bus_name".
Special treatment is given to the optional ne_branch matrix to support the TNEP problem.

Working with Matpower Data Files

The data exchange via JSON files is ideal for building algorithms, however it is hard to for humans to read and process. To that end PowerModels also has extensive support for parsing Matpower network files in the .m format.

In addition to parsing the standard Matpower parameters, PowerModels also supports extending the standard Matpower format in a number of ways as illustrated by the following examples. In these examples JSON document fragments are used to indicate the structure of the PowerModel dictionary.

Single Values

Single values are added to the root of the dictionary as follows,

mpc.const_float = 4.56

becomes

{
"const_float": 4.56
}

Nonstandard Matrices

Nonstandard matrices can be added as follows,

mpc.areas = [
    1   1;
    2   3;
];

becomes

{
"areas":{
    "1":{
        "index":1,
        "col_1":1,
        "col_2":1
    },
    "2":{
        "index":1,
        "col_1":2,
        "col_2":3
    }
}
}

Column Names

Column names can be given to nonstandard matrices using the following special comment,

%column_names%  area    refbus
mpc.areas_named = [
    4   5;
    5   6;
];

becomes

{
"areas":{
    "1":{
        "index":1,
        "area":4,
        "refbus":5
    },
    "2":{
        "index":2,
        "area":5,
        "refbus":6
    }
}
}

Standard Matrix Extensions

Finally, if a nonstandard matrix's name extends a current Matpower matrix name with an underscore, then its values will be merged with the original Matpower component data. Note that this feature requires that the nonstandard matrix has column names and has the same number of rows as the original matrix (similar to the gencost matrix in the Matpower format). For example,

%column_names%  rate_i  rate_p
mpc.branch_limit = [
    50.2    45;
    36  60.1;
    12  30;
];

becomes

{
"branch":{
    "1":{
        "index":1,
        ...(all pre existing fields)...
        "rate_i":50.2,
        "rate_p":45
    },
    "2":{
        "index":2,
        ...(all pre existing fields)...
        "rate_i":36,
        "rate_p":60.1
    },
    "3":{
        "index":3,
        ...(all pre existing fields)...
        "rate_i":12,
        "rate_p":30
    }
}
}