API

Solution

class gigpower.solution.Solution(dss_fp: str, zip_v: numpy.ndarray = array([0.1, 0.05, 0.85, 0.1, 0.05, 0.85, 0.8]))

SLACKIDX = 0

SOLUTION_PARAMS = {'I': ['lines', ['A', 'B', 'C'], <class 'complex'>], 'Srx': ['lines', ['A', 'B', 'C'], <class 'complex'>], 'Stx': ['lines', ['A', 'B', 'C'], <class 'complex'>], 'V': ['buses', ['A', 'B', 'C'], <class 'complex'>], 'Vmag': ['buses', ['A', 'B', 'C'], <class 'float'>], 'sV': ['buses', ['A', 'B', 'C'], <class 'complex'>]}

VSLACK = array([ 1. +0.j       , -0.5-0.8660254j, -0.5+0.8660254j])

calc_Srx()

calc_Stx()

calc_Vmag() → numpy.ndarray

calc_sV(bus=None)

Used to calculate total node powers, accounting for loads and capacitors, oriented according to self._orient self._orient = ‘rows’ -> returns n x 3 self._orient = ‘cols’ -> returns 3 x n param bus: if a Bus is given, updates self.sV only at the index of the Bus

get_I(orient='') → pandas.core.frame.DataFrame

Return solved line currents as a DataFrame

get_Srx(orient='') → pandas.core.frame.DataFrame

Return solved outgoing line powers as a DataFrame

get_Stx(orient='') → pandas.core.frame.DataFrame

Return solved incoming line powers as a DataFrame

get_V(orient='') → pandas.core.frame.DataFrame

Return solved voltage as a DataFrame

get_Vmag(orient='') → pandas.core.frame.DataFrame

Return solved voltage magnitude as a DataFrame

get_data_frame(param: str, orient: str = '') → pandas.core.frame.DataFrame

Returns a DataFrame for the specified solution paramater. param: must be in SOLUTION_PARAMS orient: optional, ‘rows’ or ‘cols’, defaults to self._orient

get_nominal_bus_powers(orient: str = '')

Returns a DataFrame for self.Circuit’s powers by bus param: must be in SOLUTION_PARAMS orient: optional, ‘rows’ or ‘cols’, defaults to self._orient

classmethod get_params() → Dict

returns solution paramaters as a dictionary

get_sV(orient='') → pandas.core.frame.DataFrame

Return solved total bus powers as a DataFrame

maxiter = 100

print_solution()

Prints solution values to stdout, row-major order.

classmethod set_zip_values(zip_v)

sets zip values for the Solution class param zip_V: List or nd.array with 7 values [a_z_p, a_i_p, a_pq_p, a_z_q, a_i_q, a_pq_q, min voltage pu] Note that zip values are set both on the Solution class and Circuit class

SolutionNR3

class gigpower.solution_nr3.SolutionNR3(dss_fp: str, **kwargs)

Bases: gigpower.solution.Solution

CONVERGENCE_TOLERANCE = 1e-06

change_KCL_matrices(der=0, capacitance=0, t=- 1)

map_XNR()

Set self,V, self.I, self.Stx, self.Srx, self.i, self.s based on the current value of self.XNR Written by @kathleenchang

classmethod set_zip_values(zip_v)

sets zip values for the Solution class param zip_V: List or nd.array with 7 values [a_z_p, a_i_p, a_pq_p, a_z_q, a_i_q, a_pq_q, min voltage pu] Note that zip values are set both on the Solution class and Circuit class

solve()

Solves powerflow once, updates self.XNR with solved XNR From src/nr3_python/lib/NR3.py Written by @kathleenchang

SolutionFBS

class gigpower.solution_fbs.SolutionFBS(dss_fp: str, **kwargs)

Bases: gigpower.solution.Solution

set_adj()

Sets self.adj and self.reverse_adj for FBS algorithm FBS considers transformers and voltage regulators as edges, ignoring voltage regulator connections going upstream (otherwise, the circuit has cycles and is non-radial)

classmethod set_zip_values(zip_v)

sets zip values for the Solution class param zip_V: List or nd.array with 7 values [a_z_p, a_i_p, a_pq_p, a_z_q, a_i_q, a_pq_q, min voltage pu] Note that zip values are set both on the Solution class and Circuit class

solve()

solve powerflow for self.circuit, save solution as self.V = bus complex voltage, self.I = line currents, self.S = bus powers based on fbs/fbs/fbs.py written by @elaguerta

update_current(line_in)

Updates current on a line_in based on the child node, according to tx_bus -[line_in]-> rx_bus =[0 or many lines out]=> 0 or many child buses Used during backward sweep.

update_voltage_backward(parent, child)

updates voltage at parent only for phases existing on child.

update_voltage_forward(parent, child)

updates voltage at child based on parent according to: child_node_dict[‘V’] = parent_dict[‘V’] - (parent,child).FZpu * (parent,child).I

vr_backward(vr_list)

Enforce voltage regulator equations by phase. Voltage ratio equation: reg_node.V = 1/gamma @ tx_node.V Conservation of power: reg_node.V @ [current entering reg_node]* == tx_node.V @ [current entering tx_node]* [current @ tx_node]* = reg_node.V @ [current entering reg_node]* / tx_node.V

vr_current(vr_list)

Enforce voltage regulator equations by phase. Voltage ratio equation: reg_node.V = 1/gamma @ tx_node.V Conservation of power: reg_node.V @ [current entering reg_node]* == tx_node.V @ [current entering tx_node]* [current @ tx_node]* = reg_node.V @ [current entering reg_node]* / tx_node.V

vr_forward(vr_list)

Enforce voltage regulator equations by phase. Voltage ratio equation: tx_node.V = gamma @ reg_node.V Conservation of power: reg_node.V @ [current entering reg_node]* == tx_node.V @ [current entering tx_node]* [current @ reg_node]* = tx_node.V @ [current entering tx_node]*reg_node.V

Circuit

class gigpower.circuit.Circuit(dss, Sbase=1000000)

buses

The Circuit’s BusGroup

capacitors

The Circuit’s CapacitorGroup

dss

A pointer to the OpenDSS object corresponding to this Circuit

get_aI_matrix() → numpy.ndarray

3 x n or n x 3matrix of all load.aPQ_p, aggregated by phase on bus, columns indexed by bus

get_aPQ_matrix() → numpy.ndarray

3 x n or n x 3 matrix of all load.aPQ_p, aggregated by phase on bus, columns indexed by bus

get_aZ_matrix() → numpy.ndarray

3 x n or n x 3matrix of all load.aPQ_p, aggregated by phase on bus, columns indexed by bus

get_cappu_matrix() → numpy.ndarray

3 x n or n x 3 matrix of real cappu, columns indexed by bus index

get_nominal_bus_powers() → pandas.core.frame.DataFrame

3 x n or n x 3 matrix of total nominal powers by bus

get_rx_idx_matrix()

n x 1 matrix of rx bus indices. Indexed by line index, which is the same value as in opendss

get_spu_matrix() → numpy.ndarray

3 x n or n x 3 matrix of complex spu indexed by bus index

get_total_lines()

returns number of Lines transformers, and voltage regulators * 2

get_tx_idx_matrix()

n x 1 matrix of tx bus indices, for all Lines Indexed as follows: [0, len(Lines) - 1]: Lines [len(Lines), len(Transformers)- 1]: Transformers [len(Transformers), len(VoltageRegulators)- 1]: VoltageRegulators

get_wpu_matrix() → numpy.ndarray

3 x n or n x 3matrix of all real wpu, columns indexed by bus Currently set to all zeros. TODO: Implement logic to set this as needed.

lines

The Circuit’s LineGroup

loads

The Circuit’s LoadGroup

set_kW(load_name: str, kW: float)

sets a new kW for the given Load. Updates Load.spu, Load.ppu, Load.qpu, and Bus.sum_spu

set_kvar(load_name: str, kvar: float)

sets a new kvar for the given Load. Updates Load.spu, Load.ppu, Load.qpu, and Bus.sum_spu

transformers

The Circuit’s TransformerGroup

voltage_regulators

The Circuit’s VoltageRegulatorGroup

CircuitElementGroup

class gigpower.circuit_element_group.CircuitElementGroup(dss, **kwargs)

add_element(ele, inc_num_elements=True)

adds a CircuitElement to this group param inc_num_elements: Increment self.num_elements with this addition param unique_key: overwrite existing self._key_to_element dict so that there is only one object per key

all_names()

returns all names in Group

get_element(key: Union[str, int, Tuple[str, str]])

Returns an element given a name, index, or tuple of (tx_name, rx_name)

get_elements()

returns an iterable View over all elements in the Group

get_idx(obj: Union[str, gigpower.circuit_element.CircuitElement]) → int

return the index of the object within the Group param obj: the object’s __name__, or the object itself

get_name(idx: int)

return the name of the object given its Group idx

get_phase_matrix(orient: str) → numpy.ndarray

phase matrix of 1’s where phases are present, 0’s otherwise indexed by element index, which is the same as in opendss param orient: ‘rows’ or ‘cols’

get_phase_matrix_dict() → Dict[str, numpy.ndarray]

Return a dictionary of element phase matrices, indexed by element name Phase matrix is 3 x 1, with 1’s where phase is present, zeros otherwise ex: [1, 0, 0] for element with only phase A

BusGroup

class gigpower.bus_group.BusGroup(dss, **kwargs)

Bases: gigpower.circuit_element_group.CircuitElementGroup

dss_module_name = 'Bus'

ele_class

alias of gigpower.bus.Bus

LoadGroup

class gigpower.load_group.LoadGroup(dss, bus_group, zip_v)

Bases: gigpower.circuit_element_group.CircuitElementGroup

dss_module_name = 'Loads'

ele_class

alias of gigpower.load.Load

get_ppu_matrix()

return 3 x n matrix of load.ppu values summed over Bus columns indexed by Bus index, padded by phase

get_qpu_matrix()

return 3 x n matrix of kvar values summed over Bus columns indexed by Bus index, padded by phase

get_spu_matrix()

CapacitorGroup

class gigpower.capacitor_group.CapacitorGroup(dss, bus_group)

Bases: gigpower.circuit_element_group.CircuitElementGroup

dss_module_name = 'Capacitors'

ele_class

alias of gigpower.capacitor.Capacitor

get_cappu_matrix()

return 3 x n matrix of kvar values summed over Bus columns indexed by Bus index, padded by phase

TransformerGroup

class gigpower.transformer_group.TransformerGroup(dss, bus_group, **kwargs)

Bases: gigpower.line_group.LineGroup

dss_module_name = 'Transformers'

ele_class

alias of gigpower.transformer.Transformer

get_idx(obj)

Handles Tuple representations of transformers

VoltageRegulatorGroup

class gigpower.voltage_regulator_group.VoltageRegulatorGroup(dss, bus_group)

Bases: gigpower.line_group.LineGroup

add_element(vr)

Add the VR to the VRGroup, including all the lines of the VR in the VRGroup’s adjacency matrices

dss_module_name = 'RegControls'

ele_class

alias of gigpower.voltage_regulator.VoltageRegulator

get_adj_set(reversed=False)

Return self.adj, with all voltage regulators between the same two buses into the same edge. ex: {‘650’:[‘rg60’, ‘rg60’, ‘rg60]} -> {‘650’: [‘rg60’]}

get_bus_ids(which: str)

overwrite super to get tx buses of upstream, downstream lines in vr index order param which = ‘tx’ or ‘rx’ resulting list length is 2 * self.num_elements even number indices are upstream_line tx bus indices odd number indices are downstream_line tx bus indices

get_gain_matrix() → numpy.ndarray

n x 1 matrix of NEGATIVE gain values, indexed by voltage_regulator index Negative sign for voltage ratio purposes

get_idx(obj)

Handles tuple representation. If passed a tuple, returns a list of VRs on the Line represented by the tuple