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:

Note

Only one potential reference can be set per galvanically isolated section of the network.

Available Results

The following results are available for all potential references:

Result Accessor	Default Unit	Type	Description
res_current	\(A\)	complex	Always \(0A\) for a successful load flow

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:

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, element, *, phases=None)

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 (Id) – A unique ID of the potential reference in the network references.

• element (Bus | Ground) – The bus or ground element to set as a potential reference.

• phases (str | None) –

  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.

element_type: Final = 'potential ref'

The type of the element. It is a string like "load" or "line" etc.

allowed_phases: Final

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).

element

property phases: str | None

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.

Return type:

str | None

property res_current: Q_[complex]

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.

Return type:

Q_[complex]

is_multi_phase: Final = True

Is the object multi-phase?

property network: _N_co | None

Return the network the element belong to (if any).

Return type:

_N_co | None

id

to_dict(*, include_results=True)

Convert the element to a dictionary.

Parameters:

include_results (bool) – If True (default), the results of the load flow are included in the dictionary. If no results are available, this option is ignored.

Returns:

A JSON serializable dictionary with the element’s data.

Return type:

JsonDict

to_json(path, *, include_results=True, indent=True)

Save this element to a JSON file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

• path (StrPath) – The path to the output file to write the network to.

• include_results (bool) – If True (default), the results of the load flow are included in the JSON file. If no results are available, this option is ignored.

• indent (bool) – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

Return type:

Path

results_to_dict(full=False)

Return the results of the element as a dictionary.

The results dictionary of an element contains the ID of the element, its phases, and the result. For example, bus.results_to_dict() returns a dictionary with the form:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]]}

Note that complex values (like potentials in the example above) are stored as list of [real part, imaginary part] so that it is JSON-serializable

Using the full argument, bus.results_to_dict(full=True) leads to the following results:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]], "voltages": [[230.0, 0.0]]}

The results dictionary of the network contains the results of all of its elements grouped by the element type. It has the form:

{
    "buses": [bus1_dict, bus2_dict, ...],
    "lines": [line1_dict, line2_dict, ...],
    "transformers": [transformer1_dict, transformer2_dict, ...],
    "switches": [switch1_dict, switch2_dict, ...],
    "loads": [load1_dict, load2_dict, ...],
    "sources": [source1_dict, source2_dict, ...],
    "grounds": [ground1_dict, ground2_dict, ...],
    "potential_refs": [p_ref1_dict, p_ref2_dict, ...],
}

where each dict is produced by the element’s results_to_dict() method.

Parameters:

full (bool) – If True, all the results are added in the resulting dictionary. False by default.

Returns:

The dictionary of results.

Return type:

JsonDict

results_to_json(path, *, full=False, indent=True)

Write the results of the load flow to a json file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

• path (StrPath) – The path to the output file to write the results to.

• full (bool) – If True, all the results are added in the resulting dictionary, including results computed from other results (such as voltages that could be computed from potentials). False by default.

• indent (bool) – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

Return type:

Path