roseau.load_flow.models#

This module contains the models used to represent the network elements. The models are used to build the network and to perform the load flow analysis.

Equations, diagrams, and examples can be found in the <no title> page.

Package Contents#

Classes#

AbstractBranch

Base class of all the branches (lines, switches and transformers) of the network.

Bus

A multi-phase electrical bus.

Element

An abstract class of an element in an Electrical network.

Ground

This element defines the ground.

Line

An electrical line PI model with series impedance and optional shunt admittance.

LineParameters

Parameters that define electrical models of lines.

Switch

A general purpose switch branch.

AbstractLoad

An abstract class of an electric load.

Control

Control class for flexible loads.

CurrentLoad

A constant current load.

FlexibleParameter

Flexible parameters of a flexible load.

ImpedanceLoad

A constant impedance load.

PowerLoad

A constant power load.

Projection

This class defines the projection on the feasible circle for a flexible load.

PotentialRef

A potential reference.

VoltageSource

A voltage source.

Transformer

A generic transformer model.

TransformerParameters

Parameters that define electrical models of transformers.

class AbstractBranch(id: Id, bus1: Bus, bus2: Bus, *, phases1: str, phases2: str, geometry: shapely.geometry.base.BaseGeometry | None = None)#

Bases: roseau.load_flow.models.core.Element

Base class of all the branches (lines, switches and transformers) of the network.

AbstractBranch constructor.

Parameters:
  • id – A unique ID of the branch in the network branches.

  • phases1 – The phases of the first extremity of the branch.

  • phases2 – The phases of the second extremity of the branch.

  • bus1 – The bus to connect the first extremity of the branch to.

  • bus2 – The bus to connect the second extremity of the branch to.

  • geometry – The geometry of the branch.

property phases1: str#

The phases of the branch at the first bus.

property phases2: str#

The phases of the branch at the second bus.

property bus1: Bus#

The first bus of the branch.

property bus2: Bus#

The second bus of the branch.

property res_currents: tuple[Q_[ComplexArray], Q_[ComplexArray]]#

The load flow result of the branch currents (A).

property res_powers: tuple[Q_[ComplexArray], Q_[ComplexArray]]#

The load flow result of the branch powers (VA).

property res_potentials: tuple[Q_[ComplexArray], Q_[ComplexArray]]#

The load flow result of the branch potentials (V).

property res_voltages: tuple[Q_[ComplexArray], Q_[ComplexArray]]#

The load flow result of the branch voltages (V).

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

class Bus(id: Id, *, phases: str, geometry: shapely.geometry.base.BaseGeometry | None = None, potentials: ComplexArrayLike1D | None = None, min_voltage: float | None = None, max_voltage: float | None = None)#

Bases: roseau.load_flow.models.core.Element

A multi-phase electrical bus.

Bus constructor.

Parameters:
  • id – A unique ID of the bus in the network buses.

  • phases – The phases of the bus. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases.

  • geometry – An optional geometry of the bus; a Geometry that represents the x-y coordinates of the bus.

  • potentials – An optional array-like of initial potentials of each phase of the bus. If given, these potentials are used as the starting point of the load flow computation. Either complex values (V) or a Quantity of complex values.

  • min_voltage – An optional minimum voltage of the bus (V). It is not used in the load flow. It must be a phase-neutral voltage if the bus has a neutral, phase-phase otherwise. Either a float (V) or a Quantity of float.

  • max_voltage – An optional maximum voltage of the bus (V). It is not used in the load flow. It must be a phase-neutral voltage if the bus has a neutral, phase-phase otherwise. Either a float (V) or a Quantity of float.

property phases: str#

The phases of the bus.

property potentials: Q_[ComplexArray]#

An array of initial potentials of the bus (V).

property res_potentials: Q_[ComplexArray]#

The load flow result of the bus potentials (V).

property res_voltages: Q_[ComplexArray]#

The load flow result of the bus voltages (V).

If the bus has a neutral, the voltages are phase-neutral voltages for existing phases in the order [Van, Vbn, Vcn]. If the bus does not have a neutral, phase-phase voltages are returned in the order [Vab, Vbc, Vca].

property min_voltage: Q_[float] | None#

The minimum voltage of the bus (V) if it is set.

property max_voltage: Q_[float] | None#

The maximum voltage of the bus (V) if it is set.

property res_violated: bool | None#

Whether the bus has voltage limits violations.

Returns None if the bus has no voltage limits are not set.

property short_circuits: list[dict[str, Any]]#

Return the list of short-circuits of this bus.

allowed_phases: Final#

The allowed phases for a bus are:

  • P-P-P or P-P-P-N: "abc", "abcn"

  • P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"

  • P-N: "an", "bn", "cn"

voltage_phases() list[str]#

The phases of the voltages.

propagate_limits(force: bool = False) None#

Propagate the voltage limits to galvanically connected buses.

Galvanically connected buses are buses connected to this bus through lines or switches. This ensures that these voltage limits are only applied to buses with the same voltage level. If a bus is connected to this bus through a transformer, the voltage limits are not propagated to that bus.

If this bus does not define any voltage limits, calling this method will unset the limits of the connected buses.

Parameters:

force – If False (default), an exception is raised if connected buses already have limits different from this bus. If True, the limits are propagated even if connected buses have different limits.

get_connected_buses() Iterator[Id]#

Get IDs of all the buses galvanically connected to this bus.

These are all the buses connected via one or more lines or switches to this bus.

res_voltage_unbalance() Q_[float]#

Calculate the voltage unbalance on this bus according to the IEC definition.

Voltage Unbalance Factor:

\(VUF = \frac{|V_n|}{|V_p|} * 100 (\%)\)

Where \(V_n\) is the negative-sequence voltage and \(V_p\) is the positive-sequence voltage.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

add_short_circuit(*phases: str, ground: Ground | None = None) None#

Add a short-circuit by connecting multiple phases together optionally with a ground.

Parameters:
  • phases – The phases to connect.

  • ground – If a ground is given, the phases will also be connected to the ground.

class Element(id: Id)#

Bases: abc.ABC, roseau.load_flow.utils.Identifiable, roseau.load_flow.utils.JsonMixin

An abstract class of an element in an Electrical network.

Element constructor.

Parameters:

id – A unique ID of the element in the network. Two elements of the same type cannot have the same ID.

property network: ElectricalNetwork | None#

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

allowed_phases: ClassVar[frozenset[str]]#

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

class Ground(id: Id)#

Bases: roseau.load_flow.models.core.Element

This element defines the ground.

Only buses and lines that have shunt components can be connected to a ground.

  1. Connecting to a bus:

    To connect a ground to a bus on a given phase, use the Ground.connect() method. This method lets you specify the bus to connect to as well as the phase of the connection. If the bus has a neutral and the phase is not specified, the ground will be connected to the neutral, otherwise, an error will be raised because the phase is needed.

  2. Connecting to a line with shunt components:

    To connect a ground to a line with shunt components, pass the ground object to the Line constructor. Note that the ground connection is mandatory for shunt lines.

Ground constructor.

Parameters:

id – A unique ID of the ground in the network grounds.

property res_potential: Q_[complex]#

The load flow result of the ground potential (V).

property connected_buses: dict[Id, str]#

The bus ID and phase of the buses connected to this ground.

connect(bus: Bus, phase: str = 'n') None#

Connect the ground to a bus on the given phase.

Parameters:
  • bus – The bus to connect to.

  • phase – The phase of the connection. It must be one of {"a", "b", "c", "n"} and must be present in the bus phases. Defaults to "n".

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

class Line(id: Id, bus1: Bus, bus2: Bus, *, parameters: LineParameters, length: float | Q_[float], phases: str | None = None, ground: Ground | None = None, geometry: shapely.geometry.base.BaseGeometry | None = None)#

Bases: roseau.load_flow.models.branches.AbstractBranch

An electrical line PI model with series impedance and optional shunt admittance.

Line constructor.

Parameters:
  • id – A unique ID of the line in the network branches.

  • bus1 – The first bus (aka “from_bus”) to connect to the line.

  • bus2 – The second bus (aka “to_bus”) to connect to the line.

  • parameters – Parameters defining the electric model of the line using its impedance and shunt admittance matrices. This is an instance of the LineParameters class and can be used by multiple lines.

  • length – The length of the line (in km).

  • phases – The phases of the line. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the line must be present in the phases of both connected buses. By default, the phases common to both buses are used.

  • ground – The ground element attached to the line if it has shunt admittance.

  • geometry – The geometry of the line i.e. the linestring.

property phases: str#

The phases of the line. This is an alias for phases1 and phases2.

property length: Q_[float]#

The length of the line (in km).

property parameters: LineParameters#

The parameters defining the impedance and shunt admittance matrices of line model.

property z_line: Q_[ComplexArray]#

Impedance of the line (in Ohm).

property y_shunt: Q_[ComplexArray]#

Shunt admittance of the line (in Siemens).

property max_current: Q_[float] | None#

The maximum current loading of the line (in A).

property res_series_currents: Q_[ComplexArray]#

Get the current in the series elements of the line (in A).

property res_series_power_losses: Q_[ComplexArray]#

Get the power losses in the series elements of the line (in VA).

property res_shunt_currents: tuple[Q_[ComplexArray], Q_[ComplexArray]]#

Get the currents in the shunt elements of the line (in A).

property res_shunt_power_losses: Q_[ComplexArray]#

Get the power losses in the shunt elements of the line (in VA).

property res_power_losses: Q_[ComplexArray]#

Get the power losses in the line (in VA).

property res_violated: bool | None#

Whether the line current exceeds the maximum current (loading > 100%).

Returns None if the maximum current is not set.

allowed_phases: Final#

The allowed phases for a line are:

  • P-P-P or P-P-P-N: "abc", "abcn"

  • P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"

  • P or P-N: "a", "b", "c", "an", "bn", "cn"

  • N: "n"

class LineParameters(id: Id, z_line: ComplexArrayLike2D, y_shunt: ComplexArrayLike2D | None = None, max_current: float | None = None, line_type: LineType | None = None, conductor_type: ConductorType | None = None, insulator_type: InsulatorType | None = None, section: float | Q_[float] | None = None)#

Bases: roseau.load_flow.utils.Identifiable, roseau.load_flow.utils.JsonMixin, roseau.load_flow.utils.CatalogueMixin[pandas.DataFrame]

Parameters that define electrical models of lines.

LineParameters constructor.

Parameters:
  • id – A unique ID of the line parameters, typically its canonical name.

  • z_line – The Z matrix of the line (Ohm/km).

  • y_shunt – The Y matrix of the line (Siemens/km). This field is optional if the line has no shunt part.

  • max_current – The maximum current loading of the line (A). The maximum current is optional, it is not used in the load flow but can be used to check for overloading. See also Line.res_violated.

  • line_type – The type of the line (overhead, underground, twisted). The line type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.

  • conductor_type – The type of the conductor material (Aluminum, Copper, …). The conductor type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.

  • insulator_type – The type of the cable insulator (PVC, XLPE, …). The insulator type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.

property max_current: Q_[float] | None#

The maximum current loading of the line (A) if it is set.

property line_type: LineType | None#

The type of the line. Informative only, it has no impact on the load flow.

property conductor_type: ConductorType | None#

The type of the conductor material. Informative only, it has no impact on the load flow.

property insulator_type: InsulatorType | None#

The type of the cable insulator. Informative only, it has no impact on the load flow.

property section: Q_[float] | None#

The cross section area of the cable (in mm²). Informative only, it has no impact on the load flow.

classmethod from_sym(id: Id, z0: complex | Q_[complex], z1: complex | Q_[complex], y0: complex | Q_[complex], y1: complex | Q_[complex], zn: complex | Q_[complex] | None = None, xpn: float | Q_[float] | None = None, bn: float | Q_[float] | None = None, bpn: float | Q_[float] | None = None, max_current: float | Q_[float] | None = None) typing_extensions.Self#

Create line parameters from a symmetric model.

Parameters:
  • id – A unique ID of the line parameters, typically its canonical name.

  • z0 – Impedance - zero sequence - \(r_0+x_0\cdot j\) (ohms/km)

  • z1 – Impedance - direct sequence - \(r_1+x_1\cdot j\) (ohms/km)

  • y0 – Admittance - zero sequence - \(g_0+b_0\cdot j\) (Siemens/km)

  • y1 – Conductance - direct sequence - \(g_1+b_1\cdot j\) (Siemens/km)

  • zn – Neutral impedance - \(r_{\mathrm{n}}+x_{\mathrm{n}}\cdot j\) (ohms/km)

  • xpn – Phase to neutral reactance (ohms/km)

  • bn – Neutral susceptance (siemens/km)

  • bpn – Phase to neutral susceptance (siemens/km)

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The created line parameters.

Notes

As explained in the Line parameters alternative constructor documentation, the model may be “degraded” if the computed impedance matrix is not invertible.

classmethod from_geometry(id: Id, *, line_type: LineType, conductor_type: ConductorType | None = None, insulator_type: InsulatorType | None = None, section: float | Q_[float], section_neutral: float | Q_[float] | None = None, height: float | Q_[float], external_diameter: float | Q_[float], max_current: float | Q_[float] | None = None) typing_extensions.Self#

Create line parameters from its geometry.

Parameters:
  • id – The id of the line parameters type.

  • line_type – Overhead or underground. See also LineType.

  • conductor_type – Type of the conductor. If None, ACSR is used for overhead lines and AL for underground or twisted lines. See also ConductorType.

  • insulator_type – Type of insulator. If None, XLPE is used for twisted lines and PVC for underground lines. See also InsulatorType.

  • section – Cross-section surface area of the phases (mm²).

  • section_neutral – Cross-section surface area of the neutral (mm²). If None it will be the same as the section of the other phases.

  • height – Height of the line (m). It must be positive for overhead lines and negative for underground lines.

  • external_diameter – External diameter of the cable (m).

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The created line parameters.

classmethod from_name_lv(name: str, section_neutral: float | Q_[float] | None = None, height: float | Q_[float] | None = None, external_diameter: float | Q_[float] | None = None, max_current: float | Q_[float] | None = None) typing_extensions.Self#

Method to get the electrical parameters of a LV line from its canonical name. Some hypothesis will be made: the section of the neutral is the same as the other sections, the height and external diameter are pre-defined, and the insulator is PVC.

Parameters:
  • name – The name of the line the parameters must be computed. E.g. “U_AL_150”.

  • section_neutral – Surface of the neutral (mm²). If None it will be the same as the section of the other phases.

  • height – Height of the line (m). If None a default value will be used.

  • external_diameter – External diameter of the wire (mm). If None a default value will be used.

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The corresponding line parameters.

Deprecated since version 0.6.0: Use LineParameters.from_geometry() instead.

classmethod from_name_mv(name: str, max_current: float | Q_[float] | None = None) typing_extensions.Self#

Get the electrical parameters of a MV line from its canonical name (France specific model)

Parameters:
  • name – The canonical name of the line parameters. It must be in the format lineType_conductorType_crossSection. E.g. “U_AL_150”.

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The corresponding line parameters.

classmethod catalogue_path() Path#

Get the path to the catalogue.

classmethod catalogue_data() DataFrame#

Get the catalogue data.

classmethod from_catalogue(name: str | Pattern[str] | None = None, line_type: str | None = None, conductor_type: str | None = None, insulator_type: str | None = None, section: float | Q_[float] | None = None, id: Id | None = None) typing_extensions.Self#

Create line parameters from a catalogue.

Parameters:
  • name – The name of the line parameters to get from the catalogue. It can be a regular expression.

  • line_type – The type of the line parameters to get. It can be "overhead", "twisted", or "underground". See also LineType.

  • conductor_type – The type of the conductor material (Al, Cu, …). See also ConductorType.

  • insulator_type – The type of insulator. See also InsulatorType.

  • section – The cross-section surface area of the phases (mm²).

  • id – A unique ID for the created line parameters object (optional). If None (default), the id of the created object will be its name in the catalogue.

Returns:

The created line parameters.

classmethod get_catalogue(name: str | Pattern[str] | None = None, line_type: str | None = None, conductor_type: str | None = None, insulator_type: str | None = None, section: float | Q_[float] | None = None) DataFrame#

Get the catalogue of available lines.

You can use the parameters below to filter the catalogue. If you do not specify any parameter, all the catalogue will be returned.

Parameters:
  • name – The name of the line parameters to get from the catalogue. It can be a regular expression.

  • line_type – The type of the line parameters to get. It can be "overhead", "twisted", or "underground". See also LineType.

  • conductor_type – The type of the conductor material (Al, Cu, …). See also ConductorType.

  • insulator_type – The type of insulator. See also InsulatorType.

  • section – The cross-section surface area of the phases (mm²).

Returns:

The catalogue data as a dataframe.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

Line parameters constructor from dict.

Parameters:

data – The dictionary data of the line parameters.

Returns:

The created line parameters.

class Switch(id: Id, bus1: Bus, bus2: Bus, *, phases: str | None = None, geometry: shapely.geometry.base.BaseGeometry | None = None)#

Bases: roseau.load_flow.models.branches.AbstractBranch

A general purpose switch branch.

Switch constructor.

Parameters:
  • id – A unique ID of the switch in the network branches.

  • bus1 – Bus to connect to the switch.

  • bus2 – Bus to connect to the switch.

  • phases – The phases of the switch. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the switch must be present in the phases of both connected buses. By default, the phases common to both buses are used.

  • geometry – The geometry of the switch.

property phases: str#

The phases of the switch. This is an alias for phases1 and phases2.

allowed_phases: Final#

The allowed phases for a switch are:

  • P-P-P or P-P-P-N: "abc", "abcn"

  • P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"

  • P or P-N: "a", "b", "c", "an", "bn", "cn"

  • N: "n"

class AbstractLoad(id: Id, bus: Bus, *, phases: str | None = None)#

Bases: roseau.load_flow.models.core.Element, abc.ABC

An abstract class of an electric load.

The subclasses of this class can be used to depict:
  • star-connected loads using a phases constructor argument containing “n”

  • delta-connected loads using a phases constructor argument not containing “n”

AbstractLoad constructor.

Parameters:
  • id – A unique ID of the load in the network loads.

  • bus – The bus to connect the load to.

  • phases – The phases of the load. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load, except "n", must be present in the phases of the connected bus. By default, the phases of the bus are used.

property phases: str#

The phases of the load.

property bus: Bus#

The bus of the load.

property is_flexible: bool#

Whether the load is flexible or not. Only PowerLoad can be flexible.

property res_currents: Q_[ComplexArray]#

The load flow result of the load currents (A).

property res_potentials: Q_[ComplexArray]#

The load flow result of the load potentials (V).

property res_voltages: Q_[ComplexArray]#

The load flow result of the load voltages (V).

property res_powers: Q_[ComplexArray]#

The load flow result of the “line powers” flowing into the load (VA).

allowed_phases: Final#

The allowed phases for a load are the same as for a bus.

voltage_phases() list[str]#

The phases of the load voltages.

disconnect() None#

Disconnect this load from the network. It cannot be used afterwards.

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

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.

class Control(type: ControlType, u_min: float | Q_[float], u_down: float | Q_[float], u_up: float | Q_[float], u_max: float | Q_[float], alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON)#

Bases: roseau.load_flow.utils.JsonMixin

Control class for flexible loads.

This class contains the information needed to formulate the control equations. This includes the control type, control limits, and other factors.

The control for a PowerLoad instance can be of four possible types:
  • "constant": no control is applied. In this case, a simple PowerLoad without flexible_params could have been used instead.

  • "p_max_u_production": control the maximum production active power of the load (inverter) based on the voltage \(P^{\max}_{\mathrm{prod}}(U)\).

  • "p_max_u_consumption": control the maximum consumption active power of the load based on the voltage \(P^{\max}_{\mathrm{cons}}(U)\).

  • "q_u": control the reactive power based on the voltage \(Q(U)\).

Control constructor.

Parameters:
  • type

    The type of the control:
    • "constant": no control is applied;

    • "p_max_u_production": control the maximum production active power of the load (inverter) based on the voltage \(P^{\max}_{\mathrm{prod}}(U)\);

    • "p_max_u_consumption": control the maximum consumption active power of the load based on the voltage \(P^{\max}_{\mathrm{cons}}(U)\);

    • "q_u": control the reactive power based on the voltage \(Q(U)\).

  • u_min – The minimum voltage i.e. the one the control reached the maximum action.

  • u_down – The voltage which starts to trigger the control (lower value).

  • u_up – The voltage which starts to trigger the control (upper value).

  • u_max – The maximum voltage i.e. the one the control reached its maximum action.

  • alpha – An approximation factor used by the family function (soft clip). The bigger the factor is the closer the function is to the non-differentiable function.

  • epsilon – This value is used to make a smooth inverse function. It is only useful for P control.

property u_min: Q_[float]#

The minimum voltage i.e. the one the control reached the maximum action.

property u_down: Q_[float]#

The voltage which starts to trigger the control (lower value).

property u_up: Q_[float]#

TThe voltage which starts to trigger the control (upper value).

property u_max: Q_[float]#

The maximum voltage i.e. the one the control reached its maximum action.

property alpha: float#

An approximation factor used by the family function (soft clip). The bigger the factor is the closer the function is to the non-differentiable function.

property epsilon: float#

This value is used to make a smooth inverse function.

classmethod constant() typing_extensions.Self#

Create a constant control i.e no control.

classmethod p_max_u_production(u_up: float | Q_[float], u_max: float | Q_[float], alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON) typing_extensions.Self#

Create a control of the type "p_max_u_production".

Parameters:
  • u_up – The voltage norm that triggers the control. A voltage higher than this value signals to the controller to start to reduce the production active power. On the figure, a normalised version \(U^{\mathrm{up}\,\mathrm{norm.}}\) is used.

  • u_max – The maximum norm voltage i.e. the one the control reached its maximum action. A voltage higher than this value signals to the controller to set the production active power to its minimal value. On the figure, a normalised version \(U^{\max\,\mathrm{norm.}}\) is used.

  • alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.

  • epsilon – This value is used to make a smooth inverse function.

Returns:

The "p_max_u_production" control using the provided parameters.

classmethod p_max_u_consumption(u_min: float | Q_[float], u_down: float | Q_[float], alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON) typing_extensions.Self#

Create a control of the type "p_max_u_consumption".

Parameters:
  • u_min – The minimum voltage norm i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the consumption active power to its minimal value. On the figure, a normalised version \(U^{\min\,\mathrm{norm.}}\) is used.

  • u_down – The voltage norm that triggers the control. A voltage lower than this value signals to the controller to start to reduce the consumption active power. On the figure, a normalised version \(U^{\mathrm{down}\,\mathrm{norm.}}\) is used.

  • alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.

  • epsilon – This value is used to make a smooth inverse function.

Returns:

The "p_max_u_consumption" control using the provided parameters.

classmethod q_u(u_min: float | Q_[float], u_down: float | Q_[float], u_up: float | Q_[float], u_max: float | Q_[float], alpha: float = _DEFAULT_ALPHA) typing_extensions.Self#

Create a control of the type "q_u".

Parameters:
  • u_min – The minimum voltage norm i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the reactive power to its maximal capacitive value. On the figure, a normalised version \(U^{\min\,\mathrm{norm.}}\) is used.

  • u_down – The voltage that triggers the capacitive reactive power control. A voltage lower than this value signals to the controller to start to increase the capacitive reactive power. On the figure, a normalised version \(U^{\mathrm{down}\,\mathrm{norm.}}\) is used.

  • u_up – The voltage that triggers the inductive reactive power control. A voltage higher than this value signals to the controller to start to increase the inductive reactive power. On the figure, a normalised version \(U^{\mathrm{up}\,\mathrm{norm.}}\) is used.

  • u_max – The minimum voltage i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the reactive power to its maximal inductive value. On the figure, a normalised version \(U^{\max\,\mathrm{norm.}}\) is used.

  • alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.

Returns:

The "q_u" control using the provided parameters.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

class CurrentLoad(id: Id, bus: Bus, *, currents: ComplexArrayLike1D, phases: str | None = None)#

Bases: AbstractLoad

A constant current load.

CurrentLoad constructor.

Parameters:
  • id – A unique ID of the load in the network loads.

  • bus – The bus to connect the load to.

  • currents – An array-like of the currents for each phase component. Either complex values (A) or a Quantity of complex values.

  • phases – The phases of the load. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load, except "n", must be present in the phases of the connected bus. By default, the phases of the bus are used.

property currents: Q_[ComplexArray]#

The currents of the load (Amps).

class FlexibleParameter(control_p: Control, control_q: Control, projection: Projection, s_max: float | Q_[float], q_min: float | Q_[float] | None = None, q_max: float | Q_[float] | None = None)#

Bases: roseau.load_flow.utils.JsonMixin

Flexible parameters of a flexible load.

This class encapsulate single-phase flexibility information of a flexible load:

  • The active power Control to apply;

  • The reactive power Control to apply;

  • The Projection to use when dealing with voltage violations;

  • The apparent power of the flexible load (VA). This is the maximum power the load can consume/produce. It is

    the radius of the feasible circle used by the projection

For multi-phase loads, you need to use a FlexibleParameter instance per phase.

FlexibleParameter constructor.

Parameters:
  • control_p – The control to apply on the active power.

  • control_q – The control to apply on the reactive power.

  • projection – The projection to use to have a feasible result.

  • s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.

  • q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to -s_max, but it can be further constrained.

  • q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.

property s_max: Q_[float]#

The apparent power of the flexible load (VA). It is the radius of the feasible circle.

property q_min: Q_[float]#

The minimum reactive power of the flexible load (VAr).

property q_max: Q_[float]#

The maximum reactive power of the flexible load (VAr).

classmethod constant() typing_extensions.Self#

Build flexible parameters for a constant control with a Euclidean projection.

Returns:

A constant control i.e. no control at all. It is an equivalent of the constant power load.

classmethod p_max_u_production(u_up: float | Q_[float], u_max: float | Q_[float], s_max: float | Q_[float], alpha_control: float = Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, alpha_proj: float = Projection._DEFAULT_ALPHA, epsilon_proj: float = Projection._DEFAULT_EPSILON) typing_extensions.Self#

Build flexible parameters for production P(U) control with a Euclidean projection.

Parameters:
  • u_up – The voltage upper limit value that triggers the control. If the voltage is greater than this value, the production active power is reduced.

  • u_max – The maximum voltage i.e. the one the control reached its maximum action. If the voltage is greater than this value, the production active power is reduced to zero.

  • s_max – The apparent power of the flexible inverter (VA). It is the radius of the feasible circle.

  • alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.

  • epsilon_control – This value is used to make a smooth inverse function for the control.

  • type_proj – The type of the projection to use.

  • alpha_proj – This value is used to make soft sign function and to build a soft projection function (see the diagram above).

  • epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.

Returns:

A flexible parameter which performs “p_max_u_production” control.

classmethod p_max_u_consumption(u_min: float | Q_[float], u_down: float | Q_[float], s_max: float | Q_[float], alpha_control: float = Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, alpha_proj: float = Projection._DEFAULT_ALPHA, epsilon_proj: float = Projection._DEFAULT_EPSILON) typing_extensions.Self#

Build flexible parameters for consumption P(U) control with a Euclidean projection.

Parameters:
  • u_min – The minimum voltage i.e. the one the control reached the maximum action.

  • u_down – The voltage which starts to trigger the control (lower value).

  • s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.

  • alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.

  • epsilon_control – This value is used to make a smooth inverse function for the control.

  • type_proj – The type of the projection to use.

  • alpha_proj – This value is used to make soft sign function and to build a soft projection function.

  • epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.

Returns:

A flexible parameter which performs “p_max_u_consumption” control.

classmethod q_u(u_min: float | Q_[float], u_down: float | Q_[float], u_up: float | Q_[float], u_max: float | Q_[float], s_max: float | Q_[float], q_min: float | Q_[float] | None = None, q_max: float | Q_[float] | None = None, alpha_control: float = Control._DEFAULT_ALPHA, type_proj: ProjectionType = Projection._DEFAULT_TYPE, alpha_proj: float = Projection._DEFAULT_ALPHA, epsilon_proj: float = Projection._DEFAULT_EPSILON) typing_extensions.Self#

Build flexible parameters for Q(U) control with a Euclidean projection.

Parameters:
  • u_min – The minimum voltage i.e. the one the control reached the maximum action.

  • u_down – The voltage which starts to trigger the control (lower value).

  • u_up – The voltage which starts to trigger the control (upper value).

  • u_max – The maximum voltage i.e. the one the control reached its maximum action.

  • s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.

  • q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to -s_max, but it can be further constrained.

  • q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.

  • alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.

  • type_proj – The type of the projection to use.

  • alpha_proj – This value is used to make soft sign function and to build a soft projection function.

  • epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.

Returns:

A flexible parameter which performs “q_u” control.

classmethod pq_u_production(up_up: float | Q_[float], up_max: float | Q_[float], uq_min: float | Q_[float], uq_down: float | Q_[float], uq_up: float | Q_[float], uq_max: float | Q_[float], s_max: float | Q_[float], q_min: float | Q_[float] | None = None, q_max: float | Q_[float] | None = None, alpha_control=Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, alpha_proj=Projection._DEFAULT_ALPHA, epsilon_proj=Projection._DEFAULT_EPSILON) typing_extensions.Self#

Build flexible parameters for production P(U) control and Q(U) control with a Euclidean projection.

Parameters:
  • up_up – The voltage which starts to trigger the control on the production (upper value).

  • up_max – The maximum voltage i.e. the one the control (of production) reached its maximum action.

  • uq_min – The minimum voltage i.e. the one the control reached the maximum action (reactive power control)

  • uq_down – The voltage which starts to trigger the reactive power control (lower value).

  • uq_up – The voltage which starts to trigger the reactive power control (upper value).

  • uq_max – The maximum voltage i.e. the one the reactive power control reached its maximum action.

  • s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.

  • q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to -s_max, but it can be further constrained.

  • q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.

  • alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.

  • epsilon_control – This value is used to make a smooth inverse function for the control.

  • type_proj – The type of the projection to use.

  • alpha_proj – This value is used to make soft sign function and to build a soft projection function.

  • epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.

Returns:

A flexible parameter which performs “p_max_u_production” control and a “q_u” control.

See also

p_max_u_production() and q_u() for more details.

classmethod pq_u_consumption(up_min: float | Q_[float], up_down: float | Q_[float], uq_min: float | Q_[float], uq_down: float | Q_[float], uq_up: float | Q_[float], uq_max: float | Q_[float], s_max: float | Q_[float], q_min: float | Q_[float] | None = None, q_max: float | Q_[float] | None = None, alpha_control: float | Q_[float] = Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, alpha_proj: float = Projection._DEFAULT_ALPHA, epsilon_proj: float = Projection._DEFAULT_EPSILON) typing_extensions.Self#

Build flexible parameters for consumption P(U) control and Q(U) control with a Euclidean projection.

Parameters:
  • up_min – The minimum voltage i.e. the one the active power control reached the maximum action.

  • up_down – The voltage which starts to trigger the active power control (lower value).

  • uq_min – The minimum voltage i.e. the one the control reached the maximum action (reactive power control)

  • uq_down – The voltage which starts to trigger the reactive power control (lower value).

  • uq_up – The voltage which starts to trigger the reactive power control (upper value).

  • uq_max – The maximum voltage i.e. the one the reactive power control reached its maximum action.

  • s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.

  • q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to -s_max, but it can be further constrained.

  • q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.

  • alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.

  • epsilon_control – This value is used to make a smooth inverse function for the control.

  • type_proj – The type of the projection to use.

  • alpha_proj – This value is used to make soft sign function and to build a soft projection function.

  • epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.

Returns:

A flexible parameter which performs “p_max_u_consumption” control and “q_u” control.

See also

p_max_u_consumption() and q_u() for more details.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

compute_powers(voltages: ComplexArrayLike1D, power: complex | Q_[complex]) Q_[ComplexArray]#

Compute the flexible powers for different voltages (norms)

Parameters:
  • voltages – The array of voltage norms to test with this flexible parameter.

  • power – The input theoretical power of the load.

Returns:

The flexible powers really consumed taking into account the control. One value per provided voltage norm.

plot_pq(voltages: FloatArrayLike1D, power: complex | Q_[complex], ax: Axes | None = None, voltages_labels_mask: numpy.typing.NDArray[bool_] | None = None) tuple[Axes, ComplexArray]#

Plot the “trajectory” of the flexible powers (in the (P, Q) plane) for the provided voltages and theoretical power.

Parameters:
  • voltages – Array-like of voltage norms to test with this flexible parameter.

  • power – The input theoretical power of the load.

  • ax – The optional axis to use for the plot. The current axis is used by default.

  • voltages_labels_mask – A mask to activate the plot of voltages labels. By default, no voltages annotations.

Returns:

The axis on which the plot has been drawn and the resulting flexible powers (the input if not None else the computed values).

plot_control_p(voltages: FloatArrayLike1D, power: complex | Q_[complex], ax: Axes | None = None) tuple[Axes, ComplexArray]#

Plot the flexible active power consumed (or produced) for the provided voltages and theoretical power.

Parameters:
  • voltages – Array-like of voltage norms to test with this flexible parameter.

  • power – The input theoretical power of the load.

  • ax – The optional axis to use for the plot. The current axis is used by default.

Returns:

The axis on which the plot has been drawn and the resulting flexible powers (the input if not None else the computed values).

plot_control_q(voltages: FloatArrayLike1D, power: complex | Q_[complex], ax: Axes | None = None) tuple[Axes, ComplexArray]#

Plot the flexible reactive power consumed (or produced) for the provided voltages and theoretical power.

Parameters:
  • voltages – Array-like of voltage norms to test with this flexible parameter.

  • power – The input theoretical power of the load.

  • ax – The optional axis to use for the plot. The current axis is used by default.

Returns:

The axis on which the plot has been drawn and the resulting flexible powers (the input if not None else the computed values).

class ImpedanceLoad(id: Id, bus: Bus, *, impedances: ComplexArrayLike1D, phases: str | None = None)#

Bases: AbstractLoad

A constant impedance load.

ImpedanceLoad constructor.

Parameters:
  • id – A unique ID of the load in the network loads.

  • bus – The bus to connect the load to.

  • impedances – An array-like of the impedances for each phase component. Either complex values (Ohms) or a Quantity of complex values.

  • phases – The phases of the load. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load, except "n", must be present in the phases of the connected bus. By default, the phases of the bus are used.

property impedances: Q_[ComplexArray]#

The impedances of the load (Ohms).

class PowerLoad(id: Id, bus: Bus, *, powers: ComplexArrayLike1D, phases: str | None = None, flexible_params: list[FlexibleParameter] | None = None)#

Bases: AbstractLoad

A constant power load.

PowerLoad constructor.

Parameters:
  • id – A unique ID of the load in the network loads.

  • bus – The bus to connect the load to.

  • powers – An array-like of the powers for each phase component. Either complex values (VA) or a Quantity of complex values.

  • phases – The phases of the load. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load, except "n", must be present in the phases of the connected bus. By default, the phases of the bus are used.

  • flexible_params – A list of FlexibleParameters object, one for each phase. When provided, the load is considered as flexible (or controllable) and the parameters are used to compute the flexible power of the load.

property is_flexible: bool#

Whether the load is flexible or not. Only PowerLoad can be flexible.

property powers: Q_[ComplexArray]#

The powers of the load (VA).

property res_flexible_powers: Q_[ComplexArray]#

The load flow result of the load flexible powers (VA).

This property is only available for flexible loads.

It returns the powers actually consumed or produced by each component of the load instead of the “line powers” flowing into the load connection points (as the res_powers() property does). The two properties are the same for Wye-connected loads but are different for Delta-connected loads.

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

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.

class Projection(type: ProjectionType, alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON)#

Bases: roseau.load_flow.utils.JsonMixin

This class defines the projection on the feasible circle for a flexible load.

The three possible projection types are:
  • "euclidean": for a Euclidean projection on the feasible space;

  • "keep_p": for maintaining a constant P;

  • "keep_q": for maintaining a constant Q.

Projection constructor.

Parameters:
  • type

    The type of the projection. It can be:
    • "euclidean": for an Euclidean projection on the feasible space;

    • "keep_p": for maintaining a constant P;

    • "keep_q": for maintaining a constant Q.

  • alpha – This value is used to make soft sign function and to build a soft projection function.

  • epsilon – This value is used to make a smooth sqrt function.

property alpha: float#

This value is used to make soft sign function and to build a soft projection function.

property epsilon: float#

This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

class PotentialRef(id: Id, element: Bus | Ground, *, phase: str | None = None)#

Bases: roseau.load_flow.models.core.Element

A potential reference.

This element will set the reference of the potentials in a network. Only one potential reference per galvanically isolated section of the network can be set. The potential reference can be set on any bus or ground elements. If set on a bus with no neutral and without specifying the phase, the reference will be set as Va + Vb + Vc = 0. For other buses, the default is Vn = 0.

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.

  • phase – The phase of the bus to set as a potential reference. Cannot be used with a ground. If the element passed is a bus and the phase is not given, the neutral will be used if the bus has a neutral otherwise the equation Va + Vb + Vc = 0 of the bus sets the potential reference.

property phase: str | None#

The phase of the bus set as a potential reference.

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.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

class VoltageSource(id: Id, bus: Bus, *, voltages: ComplexArrayLike1D, phases: str | None = None)#

Bases: roseau.load_flow.models.core.Element

A voltage source.

Voltage source constructor.

Parameters:
  • id – A unique ID of the voltage source in the network sources.

  • bus – The bus of the voltage source.

  • voltages – An array-like of the voltages of the source. They will be set on the connected bus. If the source has a neutral connection, the voltages are considered phase-to-neutral voltages, otherwise they are the phase-to-phase voltages. Either complex values (V) or a Quantity of complex values.

  • phases – The phases of the source. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the source, except "n", must be present in the phases of the connected bus. By default, the phases of the bus are used.

property phases: str#

The phases of the source.

property bus: Bus#

The bus of the source.

property voltages: Q_[ComplexArray]#

The voltages of the source (V).

property res_currents: Q_[ComplexArray]#

The load flow result of the source currents (A).

property res_potentials: Q_[ComplexArray]#

The load flow result of the source potentials (V).

property res_powers: Q_[ComplexArray]#

The load flow result of the source powers (VA).

allowed_phases: Final#

The allowed phases for a voltage source are the same as for a bus.

voltage_phases() list[str]#

The phases of the source voltages.

disconnect() None#

Disconnect this voltage source from the network. It cannot be used afterwards.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

class Transformer(id: Id, bus1: Bus, bus2: Bus, *, parameters: TransformerParameters, tap: float = 1.0, phases1: str | None = None, phases2: str | None = None, geometry: shapely.geometry.base.BaseGeometry | None = None)#

Bases: roseau.load_flow.models.branches.AbstractBranch

A generic transformer model.

The model parameters are defined using the parameters argument.

Transformer constructor.

Parameters:
  • id – A unique ID of the transformer in the network branches.

  • bus1 – Bus to connect the first extremity of the transformer.

  • bus2 – Bus to connect the first extremity of the transformer.

  • tap – The tap of the transformer, for example 1.02.

  • parameters – Parameters defining the electrical model of the transformer. This is an instance of the TransformerParameters class and can be used by multiple transformers.

  • phases1 – The phases of the first extremity of the transformer. A string like "abc" or "abcn" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases must be present in the connected bus. By default determined from the transformer type.

  • phases2 – The phases of the second extremity of the transformer. See phases1.

  • geometry – The geometry of the transformer.

property tap: float#

The tap of the transformer, for example 1.02.

property parameters: TransformerParameters#

The parameters of the transformer.

property max_power: Q_[float] | None#

The maximum power loading of the transformer (in VA).

property res_violated: bool | None#

Whether the transformer power exceeds the maximum power (loading > 100%).

Returns None if the maximum power is not set.

allowed_phases: Final#

The allowed phases for a transformer are:

  • P-P-P or P-P-P-N: "abc", "abcn" (three-phase transformer)

  • P-P or P-N: "ab", "bc", "ca", "an", "bn", "cn" (single-phase transformer or primary of center-tapped transformer)

  • P-P-N: "abn", "bcn", "can" (secondary of center-tapped transformer)

class TransformerParameters(id: Id, type: str, uhv: float | Q_[float], ulv: float | Q_[float], sn: float | Q_[float], p0: float | Q_[float], i0: float | Q_[float], psc: float | Q_[float], vsc: float | Q_[float], max_power: float | Q_[float] | None = None)#

Bases: roseau.load_flow.utils.Identifiable, roseau.load_flow.utils.JsonMixin, roseau.load_flow.utils.CatalogueMixin[pandas.DataFrame]

Parameters that define electrical models of transformers.

TransformerParameters constructor.

Parameters:
  • id – A unique ID of the transformer parameters, typically its canonical name.

  • type – The type of transformer parameters. It can be “single” for single-phase transformers, “center” for center-tapped transformers, or the name of the windings such as “Dyn11” for three-phase transformers. Allowed windings are “D” for delta, “Y” for wye (star), and “Z” for zigzag.

  • uhv – Phase-to-phase nominal voltages of the high voltages side (V)

  • ulv – Phase-to-phase nominal voltages of the low voltages side (V)

  • sn – The nominal power of the transformer (VA)

  • p0 – Losses during off-load test (W)

  • i0 – Current during off-load test (%)

  • psc – Losses during short-circuit test (W)

  • vsc – Voltages on LV side during short-circuit test (%)

  • max_power – The maximum power loading of the transformer (VA). It is not used in the load flow.

property uhv: Q_[float]#

Phase-to-phase nominal voltages of the high voltages side (V)

property ulv: Q_[float]#

Phase-to-phase nominal voltages of the low voltages side (V)

property sn: Q_[float]#

The nominal power of the transformer (VA)

property p0: Q_[float]#

Losses during off-load test (W)

property i0: Q_[float]#

Current during off-load test (%)

property psc: Q_[float]#

Losses during short-circuit test (W)

property vsc: Q_[float]#

Voltages on LV side during short-circuit test (%)

property max_power: Q_[float] | None#

The maximum power loading of the transformer (VA) if it is set.

to_zyk() tuple[Q_[complex], Q_[complex], Q_[float], float]#

Compute the transformer parameters z2, ym, k and orientation mandatory for some models.

Where:
  • z2: The series impedance of the transformer (Ohms).

  • ym: The magnetizing admittance of the transformer (Siemens).

  • k: The transformation ratio.

  • orientation: 1 for direct winding, -1 for reverse winding.

Returns:

The parameters (z2, ym, k, orientation).

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self#

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.

classmethod catalogue_path() Path#

Get the path to the catalogue.

classmethod catalogue_data() DataFrame#

Get the catalogue data.

classmethod from_catalogue(id: str | Pattern[str] | None = None, manufacturer: str | Pattern[str] | None = None, range: str | Pattern[str] | None = None, efficiency: str | Pattern[str] | None = None, type: str | Pattern[str] | None = None, sn: float | Q_[float] | None = None, uhv: float | Q_[float] | None = None, ulv: float | Q_[float] | None = None) typing_extensions.Self#

Build a transformer parameters from one in the catalogue.

Parameters:
  • id – The id of the transformer to get from the catalogue. It can be a regular expression.

  • manufacturer – The name of the manufacturer to get. It can be a regular expression.

  • range – The name of the product range to get. It can be a regular expression.

  • efficiency – The efficiency of the transformer get. It can be a regular expression.

  • type – The type of the transformer to get. It can be a regular expression.

  • sn – The nominal power of the transformer to get.

  • uhv – The primary side voltage of the transformer to get.

  • ulv – The secondary side voltage of the transformer to get.

Returns:

The selected transformer. If several transformers fitting the filters are in the catalogue, an error is raised.

classmethod get_catalogue(id: str | Pattern[str] | None = None, manufacturer: str | Pattern[str] | None = None, range: str | Pattern[str] | None = None, efficiency: str | Pattern[str] | None = None, type: str | Pattern[str] | None = None, sn: float | Q_[float] | None = None, uhv: float | Q_[float] | None = None, ulv: float | Q_[float] | None = None) DataFrame#

Get the catalogue of available transformers.

You can use the parameters below to filter the catalogue. If you do not specify any parameter, all the catalogue will be returned.

Parameters:
  • id – An optional manufacturer to filter the output. It can be a regular expression.

  • manufacturer – An optional manufacturer to filter the output. It can be a regular expression.

  • range – An optional product range to filter the output. It can be a regular expression.

  • efficiency – An optional efficiency to filter the output. It can be a regular expression.

  • type – An optional type of the transformer. It can be a regular expression.

  • sn – An optional nominal power of the transformer to filter the output.

  • uhv – An optional primary side voltage to filter the output.

  • ulv – An optional secondary side voltage to filter the output.

Returns:

The catalogue data as a dataframe.

classmethod extract_windings(string: str) tuple[str, str, int]#

Extract the windings and phase displacement from a given string

Parameters:

string – The string to parse.

Returns:

The first winding, the second winding, and the phase displacement