Developer Documentation

Function Naming Guidelines

Following the Julia style guidelines, functions that mutate arguments should end with !. Following the JuMP style guidelines functions beginning with an _ are intended for internal package use only (i.e. similar private scope functions). Underscores are used to separate multi-word function names and the words should typically be ordered from general to more specific, so that alphabetical sorting clusters similar functions together.

Variable and Parameter Naming Guidelines


  • _fr: from-side ('i'-node)
  • _to: to-side ('j'-node)


Defining power $s = p + j \cdot q$ and $sm = |s|$

  • s: complex power (VA)
  • sm: apparent power (VA)
  • p: active power (W)
  • q: reactive power (var)


Defining voltage $v = vm \angle va = vr + j \cdot vi$:

  • vm: magnitude of (complex) voltage (V)
  • va: angle of complex voltage (rad)
  • vr: real part of (complex) voltage (V)
  • vi: imaginary part of complex voltage (V)


Defining current $c = cm \angle ca = cr + j \cdot ci$:

  • cm: magnitude of (complex) current (A)
  • ca: angle of complex current (rad)
  • cr: real part of (complex) current (A)
  • ci: imaginary part of complex current (A)

Voltage products

Defining voltage product $w = v_i \cdot v_j$ then $w = wm \angle wa = wr + j\cdot wi$:

  • wm (short for vvm): magnitude of (complex) voltage products (V$^2$)
  • wa (short for vva): angle of complex voltage products (rad)
  • wr (short for vvr): real part of (complex) voltage products (V$^2$)
  • wi (short for vvi): imaginary part of complex voltage products (V$^2$)

Current products

Defining current product $cc = c_i \cdot c_j$ then $cc = ccm \angle cca = ccr + j\cdot cci$:

  • ccm: magnitude of (complex) current products (A$^2$)
  • cca: angle of complex current products (rad)
  • ccr: real part of (complex) current products (A$^2$)
  • cci: imaginary part of complex current products (A$^2$)

Transformer ratio

Defining complex transformer ratio $t = tm \angle ta = tr + j\cdot ti$:

  • tm: magnitude of (complex) transformer ratio (-)
  • ta: angle of complex transformer ratio (rad)
  • tr: real part of (complex) transformer ratio (-)
  • ti: imaginary part of complex transformer ratio (-)


Defining impedance $z = r + j\cdot x$:

  • r: resistance ($\Omega$)
  • x: reactance ($\Omega$)


Defining admittance $y = g + j\cdot b$:

  • g: conductance ($S$)
  • b: susceptance ($S$)

Standard Value Names

  • network ids:network, nw, n
  • conductors ids: conductor, cnd, c
  • phase ids: phase, ph, h

DistFlow derivation

For an asymmetric pi section

Following notation of [1], but recognizing it derives the SOC BFM without shunts. In a pi-section, part of the total current $I_{lij}$ at the from side flows through the series impedance, $I^{s}_{lij}$, part of it flows through the from side shunt admittance $I^{sh}_{lij}$. Vice versa for the to-side. Indicated by superscripts 's' (series) and 'sh' (shunt).

  • Ohm's law: $U^{mag}_{j} \angle \theta_{j} = U^{mag}_{i}\angle \theta_{i} - z^{s}_{lij} \cdot I^{s}_{lij}$ $\forall lij$
  • KCL at shunts: $ I{lij} = I^{s}{lij} + I^{sh}{lij}$, $ I{lji} = I^{s}{lji} + I^{sh}{lji} $
  • Observing: $I^{s}_{lij} = - I^{s}_{lji}$, $ \vert I^{s}{lij} \vert = \vert I^{s}{lji} \vert $
  • Ohm's law times its own complex conjugate: $(U^{mag}_{j})^2 = (U^{mag}_{i}\angle \theta_{i} - z^{s}_{lij} \cdot I^{s}_{lij})\cdot (U^{mag}_{i}\angle \theta_{i} - z^{s}_{lij} \cdot I^{s}_{lij})^*$
  • Defining $S^{s}_{lij} = P^{s}_{lij} + j\cdot Q^{s}_{lij} = (U^{mag}_{i}\angle \theta_{i}) \cdot (I^{s}_{lij})^*$
  • Working it out $(U^{mag}_{j})^2 = (U^{mag}_{i})^2 - 2 \cdot(r^{s}_{lij} \cdot P^{s}_{lij} + x^{s}_{lij} \cdot Q^{s}_{lij}) $ + $((r^{s}_{lij})^2 + (x^{s}_{lij})^2)\vert I^{s}_{lij} \vert^2$

Power flow balance w.r.t. branch total losses

  • Active power flow: $P_{lij}$ + $ P{lji} $ = $ g^{sh}{lij} \cdot (U^{mag}{i})^2 + r^{s}{l} \cdot \vert I^{s}{lij} \vert^2 + g^{sh}{lji} \cdot (U^{mag}_{j})^2 $
  • Reactive power flow: $Q_{lij}$ + $ Q{lji} $ = $ -b^{sh}{lij} \cdot (U^{mag}{i})^2 + x^{s}{l} \cdot \vert I^{s}{lij} \vert^2 - b^{sh}{lji} \cdot (U^{mag}_{j})^2 $
  • Current definition: $ \vert S^{s}{lij} \vert^2 $ $=(U^{mag}{i})^2 \cdot \vert I^{s}_{lij} \vert^2 $


  • Voltage from: $(U^{mag}_{i})^2 \rightarrow w_{i}$
  • Voltage to: $(U^{mag}_{j})^2 \rightarrow w_{j}$
  • Series current : $\vert I^{s}_{lij} \vert^2 \rightarrow l^{s}_{l}$

Note that $l^{s}_{l}$ represents squared magnitude of the series current, i.e. the current flow through the series impedance in the pi-model.

Power flow balance w.r.t. branch total losses

  • Active power flow: $P_{lij}$ + $ P{lji} $ = $ g^{sh}{lij} \cdot w{i} + r^{s}{l} \cdot l^{s}{l} + g^{sh}{lji} \cdot w_{j} $
  • Reactive power flow: $Q_{lij}$ + $ Q{lji} $ = $ -b^{sh}{lij} \cdot w{i} + x^{s}{l} \cdot l^{s}{l} - b^{sh}{lji} \cdot w_{j} $

Power flow balance w.r.t. branch series losses:

  • Series active power flow : $P^{s}_{lij} + P^{s}_{lji}$ $ = r^{s}{l} \cdot l^{s}{l} $
  • Series reactive power flow: $Q^{s}_{lij} + Q^{s}_{lji}$ $ = x^{s}{l} \cdot l^{s}{l} $

Valid equality to link $w_{i}, l_{lij}, P^{s}_{lij}, Q^{s}_{lij}$:

  • Nonconvex current definition: $(P^{s}_{lij})^2$ + $(Q^{s}_{lij})^2$ $=w{i} \cdot l{lij} $
  • SOC current definition: $(P^{s}_{lij})^2$ + $(Q^{s}_{lij})^2$ $\leq$ $ w{i} \cdot l{lij} $

Adding an ideal transformer

Adding an ideal transformer at the from side implicitly creates an internal branch voltage, between the transformer and the pi-section.

  • new voltage: $w^{'}_{l}$
  • ideal voltage magnitude transformer: $w^{'}_{l} = \frac{w_{i}}{(t^{mag})^2}$

W.r.t to the pi-section only formulation, we effectively perform the following substitution in all the equations above:

  • $ w{i} \rightarrow \frac{w{i}}{(t^{mag})^2}$

The branch's power balance isn't otherwise impacted by adding the ideal transformer, as such transformer is lossless.

Adding total current limits

  • Total current from: $ \vert I{lij} \vert \leq I^{rated}{l}$
  • Total current to: $ \vert I{lji} \vert \leq I^{rated}{l}$

In squared voltage magnitude variables:

  • Total current from: $ (P{lij})^2$ + $(Expr(:incomplete, "incomplete: premature end of input")){lij})^2 \leq (I^{rated}{l})^2 \cdot w{i}$
  • Total current to: $ (P{lji})^2$ + $(Expr(:incomplete, "incomplete: premature end of input")){lji})^2 \leq (I^{rated}{l})^2 \cdot w{j}$

[1] Gan, L., Li, N., Topcu, U., & Low, S. (2012). Branch flow model for radial networks: convex relaxation. 51st IEEE Conference on Decision and Control, 1–8. Retrieved from