Potential Reference

Definition

As the electrical potentials of the elements of the network are defined as a difference from a reference point, we need to define this reference point. The potential reference element sets the potential of the point where it is connected to \(0\) Volt. The symbol of a potential reference is:

A diagram of a potential reference element

Note

One and only one potential reference per galvanically isolated section of the network can be set.

Usage

It is common to consider the earth as the reference of potentials (i.e \(V_{earth} = 0V\)). In Roseau Load Flow, the ground element which represents an earth connection does not add any potential reference equation, i.e. its potential is not fixed at \(0V\). If you want to set its potential to \(0V\), you must attach a potential reference element explicitly:

import roseau.load_flow as rlf

ground = rlf.Ground(id="ground")
p_ref = rlf.PotentialRef(id="pref", element=ground)
ground.res_potential  # 0V (after the load flow calculation)

With this code snippet, you have defined the following element:

A diagram of a potential reference connected to a ground element

It is also possible to define the reference of potentials on a bus. Defining the potential reference on a bus with a neutral phase sets its potential to \(0V\). For buses without a neutral phase, the potential reference is defined by setting the sum of the potentials of the phases to \(0V\).

# Define on a bus with a neutral phase: Vn = 0V
bus1 = rlf.Bus(id="bus1", phases="abcn")
rlf.PotentialRef(id="pref1", element=bus1).phases  # "n"
bus1.res_potentials[3]  # 0V (after the load flow calculation)

# Define on a bus without a neutral phase: Va + Vb + Vc = 0V
bus2 = rlf.Bus(id="bus2", phases="abc")
rlf.PotentialRef(id="pref2", element=bus2).phases  # "abc"
bus2.res_potentials.sum()  # 0V (after the load flow calculation)

It is highly recommended to not specify the phases of the bus when defining the potential reference and to rely on the default behavior of the potential reference element. If needed though, it is possible to specify the phases of the bus whose potentials must sum to \(0V\) for the potential reference definition.

# Define the potential reference using the equation: Va + Vb = 0V
bus3 = rlf.Bus(id="bus3", phases="abcn")
rlf.PotentialRef(id="pref3", element=bus3, phases="ab").phases  # "ab"
bus3.res_potentials[:2].sum()  # 0V (after the load flow calculation)

For more information on the potential references, refer to their dedicated page in the advanced section of the documentation.

API Reference

class PotentialRef(id: Id, element: roseau.load_flow.models.buses.Bus | roseau.load_flow.models.grounds.Ground, *, phases: str | None = None, **deprecated_kw)

Bases: roseau.load_flow.models.core.Element

A potential reference.

This element sets the reference for the potentials in a network. Only one potential reference per galvanically isolated section of the network can be set.

When passed a ground, the potential of the ground is set to 0V. When passed a bus, if the bus has a neutral, the potential of the neutral is set to 0V. If the bus does not have a neutral, the sum of the potentials of the bus phases is set to 0V. If the phases are specified for a bus, the sum of the potentials of the specified phases is set to 0V.

PotentialRef constructor.

Parameters:

  • id – A unique ID of the potential reference in the network references.

  • element – The bus or ground element to set as a potential reference.

  • phases –

    The phases of the bus to set as a potential reference. Cannot be used with a ground. For the most part, you do not need to set the bus phases manually.

    If a single phase is passed, the potential of that phase will be set as a reference (0V fixed at that phase). If multiple phases are passed, the potential reference is determined by setting the sum of the bus’s potentials at these phases to zero.

    If not set, the default is to set the neutral phase as the reference for buses with a neutral, otherwise, the sum of the potentials of the bus phases is set to zero.

allowed_phases

The allowed phases for this element type.

It is a frozen set of strings like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, use print(<Element class>.allowed_phases).

original_phases
element
property phases

The phases of the bus set as a potential reference, or None if used with a ground.

The sum of the potentials of the specified phases is set to 0V.

property res_current

The sum of the currents (A) of the connection associated to the potential reference.

This sum should be equal to 0 after the load flow.

classmethod from_dict(data: JsonDict, *, include_results: bool = True)

Create an element from a dictionary created with to_dict().

Note

This method does not work on all classes that define it as some of them require additional information to be constructed. It can only be safely used on the ElectricNetwork, LineParameters and TransformerParameters classes.

Parameters:

  • data – The dictionary containing the element’s data.

  • include_results – If True (default) and the results of the load flow are included in the dictionary, the results are also loaded into the element.

Returns:

The constructed element.