mp.case_utils

class mp.case_utils

mp.case_utils - Utilities for modifying/converting MATPOWER cases.

The primary purpose of this class is to convert a single-phase MATPOWER case to an equivalent balanced three-phase case using mp.case_utils.convert_1p_to_3p() method.

mpc3p = mp.case_utils.convert_1p_to_3p(mpc)
mpc3p = mp.case_utils.convert_1p_to_3p(fname, mpc)
mp.case_utils Methods:
Method Summary
static convert_1p_to_3p(varargin)

Convert single-phase to equivalent balanced three-phase MATPOWER case.

mpc3p = mp.case_utils.convert_1p_to_3p(mpc)
mpc3p = mp.case_utils.convert_1p_to_3p(mpc, basekVA)
mpc3p = mp.case_utils.convert_1p_to_3p(mpc, basekVA, basekV)
mpc3p = mp.case_utils.convert_1p_to_3p(mpc, basekVA, basekV, freq)
mpc3p = mp.case_utils.convert_1p_to_3p(mpc, basekVA, basekV, freq, ishybrid)
mpc3p = mp.case_utils.convert_1p_to_3p(fname, mpc)
mpc3p = mp.case_utils.convert_1p_to_3p(fname, mpc, ...)

This function converts a MATPOWER case from the standard single-phase model to an equivalent balanced three-phase case. The conversion is based on the data format for the prototype unbalanced three-phase elements included in MATPOWER 8.1.

This function is useful for creating new test cases for unbalanced networks. The core idea is to generate an equivalent balanced three-phase network, which can then be converted into an unbalanced one by manually adjusting loads, lines, transformers, etc.

Inputs:

  • fname (char array) – (optional) name of the file to which the new case will be saved

  • mpc (struct or char array) – a MATPOWER case name or case struct

  • basekVA (double) – (optional, default = 1000*baseMVA) a positive scalar denoting the base power in kVA for convertion to per-unit values of the three-phase system

  • basekV (double) – a vector denoting the base voltages in kV of all buses for convertion to per-unit values of the three-phase system

  • freq (double) – a positive scalar denoting the frequency in Hz of the system

  • ishybrid (logical) – (optional, default = 0) when true, it returns the original mpc with additional fields for the three-phase equivalent of the network; when false it returns empty fields for the single-phase network elements. The buslink field is always empty.

Output:

mpc3p (struct) – a MATPOWER case struct of the equivalent balanced three-phase network, with or without the fields of the original single-phase case, depending on the value of ishybrid.

If a power flow is run for the mpc3p returned by this function, the results are the three-phase balanced equivalent of the results of the original single-phase case.

Example:

run_pf('case10ba');
mpc3p = mp.case_utils.convert_1p_to_3p('case10ba');
run_pf(mpc3p, mpoption, 'mpx', mp.xt_3p);

See also t_convert_1p_to_3p().

static z_base_change(z_old, basekV_old, basekVA_old, basekV_new, basekVA_new)

Compute a new per-unit impedance base.

z_new = mp.case_utils.z_base_change(z_old, basekV_old, basekVA_old, basekV_new, basekVA_new)
Inputs:

  • z_old (double) – original per-unit impedance base

  • basekV_old (double) – original per-unit voltage base

  • basekVA_old (double) – original per-unit power base

  • basekV_new (double) – new per-unit voltage base

  • basekVA_new (double) – new per-unit power base

Output:

z_new (double) – new per-unit impedance base

static to_consecutive_bus_numbers(mpc)

Convert a (single-phase) case to consecutive bus numbers.

mpc = mp.case_utils.remove_gen_q_lims(mpc0)
Input:

mpc0 (struct) – (single-phase) MATPOWER case struct

Outputs:

  • mpc (struct) – updated MATPOWER case struct

  • i2e (integer) – mapping of internal (new, consecutive) to external (original possibly non-consecutive) bus numbers

static remove_gen_q_lims(mpc, case_name)

Remove generator reactive power limits for co-located generators.

mpc = mp.case_utils.remove_gen_q_lims(mpc0)

The single-phase power flow uses reactive power limits, which are not (yet) included in the three-phase prototype models, to distribute reactive power dispatch for generators co-located at the same bus. This function removes those limits on the single phase case to allow for matching power flow results between a single-phase case and the three-phase case returned by mp.case_utils.convert_1p_to_3p().

Input:

mpc0 (struct) – (single-phase) MATPOWER case struct

Output:

mpc (struct) – updated MATPOWER case struct

static relocate_branch_shunts(mpc)

Move branch shunts to terminal buses for branches with off-nominal taps.

mpc = mp.case_utils.relocate_branch_shunts(mpc0)

Requires a case with consecutive bus numbering, such as guaranteed by converting a case via ext2int().

Input:

mpc0 (struct) – (single-phase) MATPOWER case struct

Output:

mpc (struct) – updated MATPOWER case struct