grg-mpdata package¶

grg_mpdata.io module¶

functions for reading and writing matpower data files

grg_mpdata.io.build_cli_parser()¶

grg_mpdata.io.main(args)¶

reads a matpower case file from a command line arguments and prints the parsed file to stdout

Parameters:	args – an argparse data structure

grg_mpdata.io.parse_mp_case_file(mpFileName)¶

opens the given path and parses it as matpower data

Parameters:	mpFileName (str) – path to the a matpower data file
Returns:	a grg_mpdata case
Return type:	Case

grg_mpdata.io.parse_mp_case_lines(mpLines)¶

parses a list of strings as matpower data

Parameters:	mpLines (list) – the list of matpower data strings
Returns:	a grg_mpdata case
Return type:	Case

grg_mpdata.io.parse_mp_case_str(mpString)¶

parses a given string as matpower data

Parameters:	mpString (str) – a matpower data file as a string
Returns:	a grg_mpdata case
Return type:	Case

grg_mpdata.io.write_mp_case_file(output_file_location, case)¶

writes a matpower case file

Parameters:	output_file_location (str) – the path of the file to write case (Case) – the data structure to write out

grg_mpdata.cmd module¶

functions for analyzing and transforming matpower data files

grg_mpdata.cmd.build_cmd_parser()¶

grg_mpdata.cmd.compare_component_lists(list_1, list_2, comp_name, index_name='index')¶

compares two lists and prints the differences to stdout. Objects in the lists are assumed to have an identification attribute.

Parameters:	list_1 (list) – the first list list_2 (list) – the second list comp_name (string) – the name of components being compared index_name (string) – the name of the object identification attribute

Returns (int):: returns the number of items that differed in the two lists

grg_mpdata.cmd.diff(case_1, case_2)¶

Compares two grg_mpdata.struct.Case objects and prints the differences to stdout.

Parameters:	case_1 – the first Matpower case case_2 – the second Matpower case

Returns (int):: returns the number of items that differed in the two cases

grg_mpdata.cmd.eq(case_1, case_2)¶

grg_mpdata.cmd.main(args)¶

reads a matpower case files and processes them based on command line arguments.

Parameters:	args – an argparse data structure

grg_mpdata.exception module¶

a collection of all grg_mpdata exception classes

exception grg_mpdata.exception.MPDataException¶

Bases: exceptions.Exception

root class for all MPData Exceptions

exception grg_mpdata.exception.MPDataParsingError¶

Bases: grg_mpdata.exception.MPDataException

for errors that occur while attempting to parse a matpower data file

exception grg_mpdata.exception.MPDataValidationError¶

Bases: grg_mpdata.exception.MPDataException

for errors that occur while attempting to validate the correctness of a parsed matpower data file

exception grg_mpdata.exception.MPDataWarning¶

Bases: exceptions.Warning

root class for all MPData Warnings

grg_mpdata.struct module¶

data structures for encoding matpower data files

class grg_mpdata.struct.Branch(index, f_bus, t_bus, br_r, br_x, br_b=0.0, rate_a=0.0, rate_b=0.0, rate_c=0.0, tap=0.0, shift=0.0, br_status=1, angmin=-360.0, angmax=360.0, pf=None, qf=None, pt=None, qt=None, mu_sf=None, mu_st=None, mu_angmin=None, mu_angmax=None)¶

Bases: object

This data structure contains key power network branch parameters. If the value of tap or shift are non-zero, the branch is considered a transformer. Angle difference bound arguments have default values for backward compatibility with an older data specification.

Parameters:

index (int) – unique branch identifier
f_bus (int) – the identifier of the from bus
t_bus (int) – the identifier of the to bus
br_r (float) – the branch resistance (p.u.)
br_x (float) – the branch reactance (p.u.)
br_b (float) – the total branch charging susceptance (p.u.)
rate_a (float) – long term rating (MVA)
rate_b (float) – short term rating (MVA)
rate_c (float) – emergency rating (MVA)
tap (float) – transformer off nominal turn ratio (p.u.)
shift (float) – positive delay transformer phase shift (degrees)
br_status (int) – branch status (in service = 1, out of service = 0)
angmin (float) – phase angle difference lower bound (degrees)
angmax (float) – phase angle difference upper bound (degrees)
pf (float, optional) – from bus active power flow (MW)
qf (float, optional) – from bus reactive power flow (MVAr)
pt (float, optional) – to bus active power flow (MW)
qt (float, optional) – to bus reactive power flow (MVAr)
mu_sf (float, optional) – KKT multiplier on from bus long term rating limit (u/MVA)
mu_st (float, optional) – KKT multiplier on to bus long term rating limit (u/MVA)
mu_angmin (float, optional) – KKT multiplier on phase angle difference lower bound (u/degree)
mu_angmax (float, optional) – KKT multiplier on phase angle difference upper bound (u/degree)

to_matpower()¶: Returns: a Matpower encoding of this data structure as a string

validate()¶: Checks that this data structure conforms to the Matpower data specification

class grg_mpdata.struct.Bus(bus_i, bus_type, pd, qd, gs, bs, area, vm, va, base_kv, zone, vmax, vmin, lam_p=None, lam_q=None, mu_vmax=None, mu_vmin=None)¶

Bases: object

This data structure contains key power network bus parameters.

Parameters:

bus_i (int) – unique bus identifier
bus_type (int) – PQ = 1, PV = 2, reference = 3, disconnected = 4
pd (float) – active power demand (MW)
qd (float) – reactive power demand (MVAr)
gs (float) – shunt conductance (MW at 1.0 volts p.u.)
bs (float) – shunt susceptance (MVAr at 1.0 volts p.u.)
area (int) – area identifier
vm (float) – voltage magnitude (volts p.u.)
va (float) – voltage angle (degrees)
base_kv (float) – base voltage (kilovolts)
zone (int) – loss zone
vmax (float) – voltage magnitude upper bound (volts p.u.)
vmin (float) – voltage magnitude lower bound (volts p.u.)
lam_p (float, optional) – Lagrange multiplier on active power KCL (u/MW)
lam_q (float, optional) – Lagrange multiplier on reactive power KCL (u/MVAr)
mu_vmax (float, optional) – KKT multiplier on voltage upper bound (u/volts p.u.)
mu_vmin (float, optional) – KKT multiplier on voltage lower bound (u/volts p.u.)

to_matpower()¶: Returns: a Matpower encoding of this data structure as a string

validate()¶: Checks that this data structure conforms to the Matpower data specification

class grg_mpdata.struct.BusName(index, name)¶

Bases: object

This data structure contains bus name parameters.

Parameters:	index (int) – unique identifier for this bus name name (str) – a bus name

to_matpower()¶: Returns: a Matpower encoding of this data structure as a string

validate()¶: Checks that this data structure conforms to the Matpower data specification

class grg_mpdata.struct.Case(name=None, version=None, baseMVA=None, bus=None, gen=None, branch=None, gencost=None, dcline=None, dclinecost=None, busname=None)¶

Bases: object

This data structure contains lists of all the key components in a power network. All arguments have default values to allow clear error messages to be generated in the validation method. At this time, only Matpower case version 2 is supported.

Parameters:

name (str) – textual name of the test case. Must be a valid matlab function identifier
version (str) – indicates the version of the test case
baseMVA (float) – the network MVA base value (MVA)
bus (list of Bus) – network buses
gen (list of Generator) – network generators
branch (list of Branch) – network branches
gencost (list of GeneratorCost, optional) – generator cost models
dcline (list of DCLine, optional) – network DC lines
dclinecost (list of DCLineCost, optional) – DC line cost models
busname (list of BusName, optional) – string names of items in bus list

remove_status_zero()¶

to_matpower()¶: Returns: a Matpower encoding of this data structure as a string

validate()¶: Checks that this data structure conforms to the Matpower data specification.

class grg_mpdata.struct.DCLine(index, f_bus, t_bus, br_status, pf, pt, qf, qt, vf, vt, pmin, pmax, qminf, qmaxf, qmint, qmaxt, loss0, loss1, mu_pmin=None, mu_pmax=None, mu_qminf=None, mu_qmaxf=None, mu_qmint=None, mu_qmaxt=None)¶

Bases: object

This data structure contains key power network dc line parameters.

Parameters:

index (int) – unique dc line identifier
f_bus (int) – the identifier of the from bus
t_bus (int) – the identifier of the to bus
br_status (int) – dc line status (in service = 1, out of service = 0)
pf (float) – from bus active power flow (MW)
pt (float) – to bus active power flow (MW)
qf (float) – from bus reactive power flow (MVAr)
qt (float) – to bus reactive power flow (MVAr)
vf (float) – from bus voltage magnitude setpoint (volts p.u.)
vt (float) – to bus voltage magnitude setpoint (volts p.u.)
pmin (float) – active power flow lower bound (MW), from bus if >= 0, to bus if < 0
pmax (float) – active power flow upper bound (MW), from bus if >= 0, to bus if < 0
qminf (float) – from bus reactive power flow lower bound (MVAr)
qmaxf (float) – from bus reactive power flow upper bound (MVAr)
qmint (float) – to bus reactive power flow lower bound (MVAr)
qmaxt (float) – to bus reactive power flow upper bound (MVAr)
loss0 (float) – constant term in from bus active power loss function (MW)
loss1 (float) – linear term in from bus active power loss function (scalar)
mu_pmin (float, optional) – KKT multiplier on from bus active power lower bound (u/MW)
mu_pmax (float, optional) – KKT multiplier on from bus active power upper bound (u/MW)
mu_qminf (float, optional) – KKT multiplier on from bus reactive power lower bound (u/MVAr)
mu_qmaxf (float, optional) – KKT multiplier on from bus reactive power upper bound (u/MVAr)
mu_qmint (float, optional) – KKT multiplier on to bus reactive power lower bound (u/MVAr)
mu_qmaxt (float, optional) – KKT multiplier on to bus reactive power upper bound (u/MVAr)

to_matpower()¶: Returns: a Matpower encoding of this data structure as a string

validate()¶: Checks that this data structure conforms to the Matpower data specification

class grg_mpdata.struct.DCLineCost(index, model, startup=0, shutdown=0, ncost=0, cost=[])¶

Bases: grg_mpdata.struct.MatpowerCost

This data structure contains key power generator cost model parameters. Note that the generator cost identifier (i.e. index) is used to link the cost model to a particular generator

The piecewise linear model \(f(x)\) is defined by, the coordinates \((\boldsymbol {cost}_0, \boldsymbol {cost}_1)\), \((\boldsymbol {cost}_2, \boldsymbol {cost}_3)\), \(\dots\) , \((\boldsymbol {cost}_{2 \boldsymbol {ncost} - 1}, \boldsymbol {cost}_{2 \boldsymbol {ncost}})\) of the end/break-points of the piecewise linear cost.

The polynomial cost model is defined as, \(f(x) = \sum_{i \in 1 .. \boldsymbol {ncost}} \boldsymbol {cost}_{i-1} x^{\boldsymbol {ncost} - i}\).

Parameters:

index (int) – unique generator cost identifier
model (int) – generator cost model (piecewise linear = 1, polynomial = 2)
startup (float) – startup costs (US Dollars)
shutdown (float) – shutdown costs (US Dollars)
ncost (int) – number of data points or cost coefficients
cost (list of float) – the list of data points or cost coefficients (US Dollars/hour), if a polynomial model it should have ncost values, if a piecewise linear model it should have 2*ncost values

class grg_mpdata.struct.Generator(index, gen_bus, pg, qg, qmax, qmin, vg, mbase, gen_status, pmax, pmin, pc1=0, pc2=0, qc1min=0, qc1max=0, qc2min=0, qc2max=0, ramp_agc=0, ramp_10=0, ramp_30=0, ramp_q=0, apf=0, mu_pmax=None, mu_pmin=None, mu_qmax=None, mu_qmin=None)¶

Bases: object

This data structure contains key power generator parameters. Some arguments have default values of 0 for backward compatibility with an older data specification.

Parameters:

index (int) – unique generator identifier
gen_bus (int) – the identifier of the bus that this generator is connected to
pg (float) – active power output (MW)
qg (float) – reactive power output (MVAr)
qmax (float) – reactive power output upper bound (MVAr)
qmin (float) – reactive power output lower bound (MVAr)
vg (float) – voltage magnitude setpoint (volts p.u.)
mbase (float) – machine mva base (MVA)
gen_status (int) – generator status (in service > 0, out of service <= 0)
pmax (float) – active power output upper bound (MW)
pmin (float) – active power output lower bound (MW)
pc1 (float) – PQ capability curve, active power lower bound (MW)
pc2 (float) – PQ capability curve, active power upper bound (MW)
qc1min (float) – reactive power output lower bound, at PC1 (MVAr)
qc1max (float) – reactive power output upper bound, at PC1 (MVAr)
qc2min (float) – reactive power output lower bound, at PC2 (MVAr)
qc2max (float) – reactive power output upper bound, at PC2 (MVAr)
ramp_agc (float) – AGC ramp rate (MW/min)
ramp_10 (float) – ramp rate for 10 minute reserves (MW)
ramp_30 (float) – ramp rate for 30 minute reserves (MW)
ramp_q (float) – ramp rate for reactive power (MVAr/min)
apf (float) – area participation factor
mu_pmax (float, optional) – KKT multiplier on active power output upper bound (u/MW)
mu_pmin (float, optional) – KKT multiplier on active power output lower bound (u/MW)
mu_qmax (float, optional) – KKT multiplier on reactive power output upper bound (u/MVAr)
mu_qmin (float, optional) – KKT multiplier on reactive power output lower bound (u/MVAr)

to_matpower()¶: Returns: a Matpower encoding of this data structure as a string

validate()¶: Checks that this data structure conforms to the Matpower data specification

class grg_mpdata.struct.GeneratorCost(index, model, startup=0, shutdown=0, ncost=0, cost=[])¶

Bases: grg_mpdata.struct.MatpowerCost

This data structure contains key power generator cost model parameters. Note that the generator cost identifier (i.e. index) is used to link the cost model to a particular generator

The piecewise linear model \(f(x)\) is defined by, the coordinates \((\boldsymbol {cost}_0, \boldsymbol {cost}_1)\), \((\boldsymbol {cost}_2, \boldsymbol {cost}_3)\), \(\dots\) , \((\boldsymbol {cost}_{2 \boldsymbol {ncost} - 1}, \boldsymbol {cost}_{2 \boldsymbol {ncost}})\) of the end/break-points of the piecewise linear cost.

The polynomial cost model is defined as, \(f(x) = \sum_{i \in 1 .. \boldsymbol {ncost}} \boldsymbol {cost}_{i-1} x^{\boldsymbol {ncost} - i}\).

Parameters:

index (int) – unique generator cost identifier
model (int) – generator cost model (piecewise linear = 1, polynomial = 2)
startup (float) – startup costs (US Dollars)
shutdown (float) – shutdown costs (US Dollars)
ncost (int) – number of data points or cost coefficients
cost (list of float) – the list of data points or cost coefficients (US Dollars/hour), if a polynomial model it should have ncost values, if a piecewise linear model it should have 2*ncost values

class grg_mpdata.struct.MatpowerCost(index, model, startup=0, shutdown=0, ncost=0, cost=[])¶

Bases: object

This data structure contains key power generator cost model parameters. Note that the generator cost identifier (i.e. index) is used to link the cost model to a particular generator

The piecewise linear model \(f(x)\) is defined by, the coordinates \((\boldsymbol {cost}_0, \boldsymbol {cost}_1)\), \((\boldsymbol {cost}_2, \boldsymbol {cost}_3)\), \(\dots\) , \((\boldsymbol {cost}_{2 \boldsymbol {ncost} - 1}, \boldsymbol {cost}_{2 \boldsymbol {ncost}})\) of the end/break-points of the piecewise linear cost.

The polynomial cost model is defined as, \(f(x) = \sum_{i \in 1 .. \boldsymbol {ncost}} \boldsymbol {cost}_{i-1} x^{\boldsymbol {ncost} - i}\).

Parameters:

index (int) – unique generator cost identifier
model (int) – generator cost model (piecewise linear = 1, polynomial = 2)
startup (float) – startup costs (US Dollars)
shutdown (float) – shutdown costs (US Dollars)
ncost (int) – number of data points or cost coefficients
cost (list of float) – the list of data points or cost coefficients (US Dollars/hour), if a polynomial model it should have ncost values, if a piecewise linear model it should have 2*ncost values

to_matpower()¶: Returns: a Matpower encoding of this data structure as a string

validate()¶: Checks that this data structure conforms to the Matpower data specification

Module contents¶

a package for reading and writing of matpower data files