Transformers¶

Definition¶

Roseau Load Flow can model single-phase, center-tapped and three-phase transformers.

Transformer parameters¶

Transformers are modeled with the following parameters:

\(\mathrm{VG}\): the vector group of the transformer. This parameter is called vg in the code.
\(U_\mathrm{HV}\): the phase-to-phase nominal voltage of the high voltage side (in V). This parameter is called uhv in the code.
\(U_\mathrm{LV}\): the phase-to-phase nominal voltage of the low voltage side (in V). This parameter is called ulv in the code.
\(S^n\): the nominal power of the transformer (in VA). This parameter is called sn in the code.
\(Z_2\): the series impedance located at the low voltage side of the transformer. It represents non-ideal transformer losses due to winding resistance and leakage reactance. This parameter is called z2 in the code.
\(Y_m\): the magnetizing admittance located at the high voltage side of the transformer. It represents non-ideal transformer losses due to core magnetizing inductance and iron losses. This parameter is called ym in the code.

The vector group defines the type of transformer and its high voltage and low voltage winding configuration:

"Ii0" or "Ii6": a single-phase transformer, in-phase or in opposition respectively;
"Iii0" or "Iii6": a center-tapped transformer, in-phase or in opposition respectively;
"Dd0", "Dyn11", etc.: a three-phase transformer with different winding configurations. For a full list of supported three-phase transformer configurations, please refer to the three-phase transformer models page.

\(Z_2\) and \(Y_m\) are usually obtained from the following results of open-circuit and short-circuit tests:

\(i^0\): the current during open-circuit test (in %). This parameter is called i0 in the code.
\(P^0\): the losses during open-circuit test (in W). This parameter is called p0 in the code.
\(P^\mathrm{sc}\): the losses during short-circuit test (in W). This parameter is called psc in the code.
\(V^\mathrm{sc}\): the voltage on LV side during short-circuit test (in %). This parameter is called vsc in the code.

First, we define the following quantities:

\(i_\mathrm{HV}^n=\dfrac{S^n}{U_\mathrm{HV}}\): the nominal current of the high voltage winding of the transformer.
\(i_\mathrm{LV}^n=\dfrac{S^n}{U_\mathrm{LV}}\): the nominal current of the low voltage winding of the transformer.

Open-circuit and short-circuit tests¶

Open-circuit test¶

Let \(P^0\) be the no-load losses and \(i^0_\mathrm{HV}\) be the current in the high voltage winding of the transformer during the no-load (open-circuit) test. The following values can be computed:

\[\begin{split}\begin{aligned} i^0&=100\cdot \frac{i_\mathrm{HV}^0}{i_\mathrm{HV}^n} \qquad \text{(in \%)} \\% S^0 &= U^0\cdot i_\mathrm{HV}^0 = U_\mathrm{HV}\cdot (i^0\cdot i_\mathrm{HV}^n) = i^0\cdot S^n \qquad \text{(in VA)}\\% R_{\mathrm{iron}} &= \dfrac{U_\mathrm{HV}^2}{P^0} \qquad \text{(in Ohm)}\\% L_{\mathrm{m}} &= \dfrac{U_\mathrm{HV}^2}{\omega\sqrt{{S^0}^2-{P^0}^2}} \text{(in H)}% \end{aligned}\end{split}\]

Then, \(\underline{Y_{\mathrm{m}}}\) can be deduced:

\[\begin{split}\underline{Y_{\mathrm{m}}} = \left\{ \begin{aligned} \frac{1}{R_{\mathrm{iron}}} + \frac{1}{j\omega L_{\mathrm{m}}} & \qquad \text{if } S^0 > P^0 \\% \frac{1}{R_{\mathrm{iron}}} & \qquad \text{otherwise}% \end{aligned} \right.\end{split}\]

Short-circuit test¶

Let \(P^{\mathrm{sc}}\) be the short-circuit losses and \(U_\mathrm{LV}^\mathrm{sc}\) be the voltage on LV side during the short-circuit test. The following values can be computed:

\[\begin{split}\begin{aligned} V^{\mathrm{sc}}&= 100\cdot \frac{U_\mathrm{LV}^\mathrm{sc}}{U_\mathrm{LV}} \qquad \text{(in \%)} \\ Z_2&=\frac{U_\mathrm{LV}^\mathrm{sc}}{i_\mathrm{LV}^n} =U_\mathrm{LV}^\mathrm{sc}\cdot\frac{U_\mathrm{LV}}{S^n} =V^\mathrm{sc}\cdot\frac{U_\mathrm{LV}^2}{S^n} \qquad \text{(in Ohm)}\\ R_2&=\frac{P^\mathrm{sc}}{{i_\mathrm{LV}^n}^2} =\frac{P^\mathrm{sc}\cdot U_\mathrm{LV}^2}{{S^n}^2} \qquad \text{(in Ohm)} \\ X_2&=L_2\cdot\omega = \sqrt{Z_2^2-R_2^2} \qquad \text{(in Ohm)} \end{aligned}\end{split}\]

Then, \(\underline{Z_2}\) can be deduced:

\[\underline{Z_2} = R_2+j\cdot X_2\]

Available Results¶

The following results are available for all transformers:

Result Accessor	Default Unit	Type	Description
`res_potentials`⭑	\(V\)	2 complex arrays	The potentials of each phase of the transformer
`res_currents`⭑	\(A\)	2 complex arrays	The currents flowing into each phase of the transformer
`res_powers`⭑	\(V\!A\)	2 complex arrays	The powers flowing into each phase of the transformer
`res_voltages`⭑	\(V\)	2 complex arrays	The phase-to-neutral voltages if the transformer has a neutral, the phase-to-phase voltages otherwise
`res_power_losses`	\(V\!A\)	complex	The total power loss in the transformer
`res_loading`	\(\mathrm{pu}\)	number	The loading of the transformer compared to its nominal power
`res_violated`	-	boolean	Indicates if the transformer loading exceeds its maximal loading

Note

The result accessors marked with ⭑ contain tuples for the results of the HV and LV sides of the transformer. These are the old accessors to the results of the sides of the transformer. They may be deprecated in the future. The new interface is to use <side>.res_* presented below.

Additionally, the following results are available on each side of the transformer accessible with <side>. prefix where <side> is either side_hv or side_lv:

Result Accessor	Default Unit	Type	Description
`<side>.res_potentials`	\(V\)	complex array	The potentials of each phase of the corresponding transformer side
`<side>.res_currents`	\(A\)	complex array	The currents flowing into each phase of the corresponding transformer side
`<side>.res_powers`	\(V\!A\)	complex array	The powers flowing into each phase of the corresponding transformer side
`<side>.res_voltages`	\(V\)	complex array	The voltages of the corresponding transformer side: phase-to-neutral if it has a neutral, phase-to-phase otherwise

And the following results are available for transformer sides with a neutral and at least one phase:

Result Accessor	Default Unit	Type	Description
`<side>.res_voltages_pn`	\(V\)	complex array	The phase-to-neutral voltages of the corresponding transformer side
`<side>.res_voltage_levels_pn`	\(\mathrm{pu}\)	number array	The voltage levels of each phase of the corresponding transformer side (\(\sqrt{3} V_{pn} / V_\mathrm{nom}\))

And the following results are available for transformer sides with more than one phase:

Result Accessor	Default Unit	Type	Description
`<side>.res_voltages_pp`	\(V\)	complex array	The phase-to-phase voltages of the corresponding transformer side
`<side>.res_voltage_levels_pp`	\(\mathrm{pu}\)	number array	The voltage levels of each phase of the corresponding transformer side (\(V_{pp} / V_\mathrm{nom}\))

And the following results are available for three-phase transformers:

Result Accessor	Default Unit	Type	Description
`<side>.res_voltage_unbalance()`	\(\%\)	number	The voltage unbalance of the corresponding transformer side according to the IEC, IEEE or NEMA definition
`<side>.res_current_unbalance()`	\(\%\)	number	The Current Unbalance Factor (CUF) of the transformer side

Usage¶

To define the parameters of the transformers, use the TransformerParameters class. Depending on the information you have, you can choose between the following methods:

Using pre-defined transformers in the catalogue¶

If you don’t have all the information needed to model the transformer but you know its nominal power and voltage, check if your transformer is already defined in the catalogue. You can then create the transformer parameters using the from_catalogue() method:

transformer_params = rlf.TransformerParameters.from_catalogue(
    name="SE Minera A0Ak 50kVA 15/20kV(15) 410V Yzn11"
)

Refer to the catalogues page for more information.

Using open-circuit and short-circuit test results¶

If your transformer is not in the catalogue but you have the results of the open-circuit and short-circuit tests, you can create the transformer parameters using the from_open_and_short_circuit_tests() method:

import roseau.load_flow as rlf

# The transformer parameters for a single-phase transformer
transformer_params_1ph = rlf.TransformerParameters.from_open_and_short_circuit_tests(
    id="transformer_params_1ph",
    vg="Ii0",  # <--- single-phase transformer
    uhv=rlf.Q_(20, "kV"),
    ulv=rlf.Q_(400, "V"),
    sn=rlf.Q_(160, "kVA"),
    p0=rlf.Q_(300, "W"),
    i0=rlf.Q_(1.4, "%"),
    psc=rlf.Q_(2000, "W"),
    vsc=rlf.Q_(4, "%"),
)
assert transformer_params_1ph.type == "single-phase"

# The transformer parameters for a three-phase transformer
transformer_params_3ph = rlf.TransformerParameters.from_open_and_short_circuit_tests(
    id="transformer_params_3ph",
    vg="Dyn11",  # <--- three-phase transformer with (Δ) HV leading (Y) LV by 30°
    uhv=rlf.Q_(20, "kV"),
    ulv=rlf.Q_(400, "V"),
    sn=rlf.Q_(160, "kVA"),
    p0=rlf.Q_(300, "W"),
    i0=rlf.Q_(1.4, "%"),
    psc=rlf.Q_(2000, "W"),
    vsc=rlf.Q_(4, "%"),
)
assert transformer_params_3ph.type == "three-phase"

# The transformer parameters for a center-tapped transformer
transformer_params_ct = rlf.TransformerParameters.from_open_and_short_circuit_tests(
    id="transformer_params_ct",
    vg="Iii0",  # <--- center-tapped transformer
    uhv=rlf.Q_(20, "kV"),
    ulv=rlf.Q_(400, "V"),
    sn=rlf.Q_(160, "kVA"),
    p0=rlf.Q_(300, "W"),
    i0=rlf.Q_(1.4, "%"),
    psc=rlf.Q_(2000, "W"),
    vsc=rlf.Q_(4, "%"),
)
assert transformer_params_ct.type == "center-tapped"

# Available vector groups:
print(rlf.TransformerParameters.allowed_vector_groups)
# "Dd0", "Dd6", ..., "Ii0", "Ii6", "Iii0", "Iii6",

Using the transformer parameters directly¶

If you know the \(Z_2\) and \(Y_m\) values, you can create the transformer parameters directly:

transformer_params_1ph = rlf.TransformerParameters(
    id="transformer_params_1ph",
    vg="Ii0",
    uhv=rlf.Q_(20, "kV"),
    ulv=rlf.Q_(400, "V"),
    sn=rlf.Q_(160, "kVA"),
    z2=rlf.Q_(0.0125 + 0.038j, "ohm"),
    ym=rlf.Q_(7.5e-7 - 5.5e-6j, "S"),
)

Using data from another software¶

If you have the transformer parameters in another software, you can use the available data exchange methods to create the transformer parameters. We currently support PowerFactory and OpenDSS.

For OpenDSS, use the from_open_dss() method. Refer to the OpenDss section in the data exchange page for more information.
For PowerFactory, use the from_power_factory() method. Refer to the PowerFactory section in the data exchange page for more information.

Available models¶

The following transformer models are available in Roseau Load Flow:

Transformers

API Reference¶

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.
vg –
The vector group of the transformer.

For three-phase transformers, Dyn11 denotes a delta-wye connection with -30° phase displacement. Allowed windings are D for delta, Y for wye, Z for zigzag.

For single-phase transformers, Ii0 denotes a normal in-phase connection and Ii6 denotes an inverted connection.

For center-tapped transformers, Iii0 denotes a normal in-phase connection and Iii6 denotes an inverted connection.
uhv – Rated phase-to-phase voltage of the HV side (V)
ulv – Rated no-load phase-to-phase voltage of the LV side (V)
sn – The nominal power of the transformer (VA)
z2 – The series impedance located at the LV side of the transformer.
ym – The magnetizing admittance located at the HV side of the transformer.
fn – The nominal frequency of the transformer (Hz). Default is None. The frequency is not currently used in the transformer model as the transformer parameters already in Ohm and Siemens. It is only used when converting the transformer parameters to other formats, like PowerFactory.
manufacturer – The name of the manufacturer for the transformer. Informative only, it has no impact on the load flow. It is filled automatically when the parameters when imported from the catalogue.
range – The product range for the transformer as defined by the manufacturer. Informative only, it has no impact on the load flow. It is filled automatically when the parameters when imported from the catalogue.
efficiency – The efficiency class of the transformer. Informative only, it has no impact on the load flow. It is filled automatically when the parameters when imported from the catalogue. The efficiency class used in the catalogue follows the Eco-Design requirements as defined by the EN 50629 standard.
cooling – The cooling class of the transformer according to IEC 60076 (ONAN, ONAF, etc.). Informative only, it has no impact on the load flow. The cooling class is defined by IEC 60076 parts 2, 11 and 15.
insulation – The transformer insulation technology (dry-type, liquid-immersed, gas-filled). Informative only, it has no impact on the load flow.

is_multi_phase: Final = True: Is the object multi-phase?

allowed_vector_groups: Final: Allowed vector groups for transformers.

property type: Literal['three-phase', 'single-phase', 'center-tapped']

The type of transformer parameters.

It can be three-phase, single-phase or center-tapped.

property vg: str

The vector group of the transformer.

For three-phase transformers, Dyn11 denotes a delta-wye connection with 30° lead phase displacement. Allowed windings are D for delta, Y for wye, Z for zigzag.

For single-phase transformers, Ii0 denotes a normal in-phase connection and Ii6 denotes an inverted connection.

For center-tapped transformers, Iii0 denotes a normal in-phase connection and Iii6 denotes an inverted connection.

property whv: str

The HV winding of the transformer.

The following values are used: - D: a Delta connection - Y or Yn: a Wye connection - Z or Zn: a Zigzag connection - I: single-phase

property wlv: str

The LV winding of the transformer.

The following values are used: - d: a Delta connection - y or yn: a Wye connection - z or zn: a Zigzag connection - i: single-phase - ii split-phase (i.e center-tapped)

property clock: int: The clock number (phase displacement) as indicated by the vector group.

winding1

winding2

phase_displacement

property uhv: Q_[float]: Rated phase-to-phase voltage of the HV side (V).

property ulv: Q_[float]: Rated no-load phase-to-phase voltage of the LV side (V).

property sn: Q_[float]: The nominal power of the transformer (VA).

property fn: Q_[float]: The nominal frequency of the transformer (Hz).

property z2: Q_[complex]: The series impedance of the transformer (Ohm).

property ym: Q_[complex]: The magnetizing admittance of the transformer (S).

property k: Q_[float]: The transformation ratio of the transformer.

property orientation: float

1 for direct windings or -1 for reverse windings.

Type:: The orientation of the transformer

property p0: Q_[float]: Losses during open-circuit test (W).

property i0: Q_[float]: Current during open-circuit test (%).

property psc: Q_[float]: Losses during short-circuit test (W).

property vsc: Q_[float]: Voltages on LV side during short-circuit test (%).

property manufacturer: str | None

The name of the manufacturer for the transformer.

Informative only, it has no impact on the load flow. It is filled automatically when the parameters are imported from the catalogue.

property range: str | None

The product range for the transformer as defined by the manufacturer.

Informative only, it has no impact on the load flow. It is filled automatically when the parameters are imported from the catalogue.

property efficiency: str | None

The efficiency class of the transformer.

Informative only, it has no impact on the load flow. It is filled automatically when the parameters imported from the catalogue. The efficiency class used in the catalogue follows the Eco-Design requirements as defined by the EN 50629 standard.

property cooling: TransformerCooling | None: The cooling class of the transformer according to IEC 60076 (ONAN, ONAF, AN, …).

property insulation: TransformerInsulation | None: The insulation technology of the transformer (dry-type, liquid-immersed, gas-filled).

Create a transformer parameters object from PowerFactory “TypTr2” data.

Note that only two-winding three-phase transformers are currently supported.

Parameters:

id – A unique ID of the transformer parameters.
tech – PwF parameter nt2ph (Technology). The technology of the transformer; either ‘single-phase’ or 2 for single-phase transformers or ‘three-phase’ or 3 for three-phase transformers.
sn – PwF parameter strn (Rated Power). The rated power of the transformer in (MVA).
uhv – PwF parameter utrn_h (Rated Voltage HV-Side). The rated phase-to-phase voltage of the transformer on the HV side.
ulv – PwF parameter utrn_l (Rated Voltage LV-Side). The rated phase-to-phase voltage of the transformer on the LV side.
vg_hv – PwF parameter tr2cn_h (Vector Group HV-Side). The vector group of the high voltage side. It can be one of ‘D’, ‘Y’, ‘Yn’, ‘Z’, ‘Zn’.
vg_lv – PwF parameter tr2cn_l (Vector Group LV-Side). The vector group of the low voltage side. It can be one of ‘d’, ‘y’, ‘yn’, ‘z’, ‘zn’.
phase_shift – PwF parameter nt2ag (Vector Group Phase Shift). The phase shift of the vector group in (degrees).
uk – PwF parameter uktr (Positive Sequence Impedance Short-Circuit Voltage). The positive sequence impedance i.e the voltage in (%) obtained from the short-circuit test.
pc – PwF parameter pcutr (Positive Sequence Impedance Copper Losses). The positive sequence impedance copper losses i.e the power in (kW) obtained from the short circuit test.
curmg – PwF parameter curmg (Magnetizing Impedance - No Load Current). The magnetizing current i.e. the current in (%) obtained from the no-load (open-circuit) test.
pfe – PwF parameter pfe (Magnetizing Impedance - No Load Losses). The magnetizing impedance i.e. the power losses in (kW) obtained from the no-load test.
manufacturer – The name of the manufacturer for the transformer. Informative only, it has no impact on the load flow.
range – The name of the product range for the transformer. Informative only, it has no impact on the load flow.
efficiency – The efficiency class of the transformer. Informative only, it has no impact on the load flow.
cooling – The cooling class of the transformer according to IEC 60076 (ONAN, ONAF, etc.). Informative only, it has no impact on the load flow. The cooling class is defined by IEC 60076 parts 2, 11 and 15.
insulation – The transformer insulation technology (dry-type, liquid-immersed, gas-filled). Informative only, it has no impact on the load flow.

Returns:

The corresponding transformer parameters object.

Create a transformer parameters object from OpenDSS “Transformer” data.

Note that only two-winding three-phase transformers are currently supported.

Parameters:

id – The unique ID of the transformer parameters.
conns – OpenDSS parameter: Conns. Connection of the windings. One of {wye | ln} for wye connected banks or {delta | ll} for delta (line-line) connected banks.
kvs – OpenDSS parameter: KVs. Rated phase-to-phase voltage of the windings, kV. This is a sequence of two values equivalent to (Up, Us).
kvas – OpenDSS parameter: KVAs. Base kVA rating (OA rating) of the windings. Note that only one value is accepted as only two-winding transformers are accepted.
xhl – OpenDSS parameter: XHL. Percent reactance high-to-low (winding 1 to winding 2).
loadloss – OpenDSS parameter: %Loadloss. Percent Losses at rated load. Causes the %r values (cf. the %Rs parameter) to be set for windings 1 and 2.
noloadloss – OpenDSS parameter: %Noloadloss. Percent No load losses at nominal voltage. Default is 0. Causes a resistive branch to be added in parallel with the magnetizing inductance.
imag – OpenDSS parameter: %Imag. Percent magnetizing current. Default is 0. An inductance is used to represent the magnetizing current. This is embedded within the transformer model as the primitive Y matrix is being computed.
leadlag – OpenDSS parameter: LeadLag. {Lead | Lag | ANSI | Euro} Designation in mixed Delta-wye connections signifying the relationship between HV to LV winding. Default is ANSI 30 deg lag, e.g., Dy1 of Yd1 vector group. To get typical European Dy11 connection, specify either “lead” or “Euro”.
rs – OpenDSS parameter: %Rs. [OPTIONAL] Percent resistance of the windings on the rated kVA base. Only required if loadloss is not passed. Note that if rs is used along with loadloss, they have to have equivalent values. For a two-winding transformer, %rs=[0.1, 0.1] is equivalent to %loadloss=0.2.
manufacturer – The name of the manufacturer for the transformer. Informative only, it has no impact on the load flow.
range – The name of the product range for the transformer. Informative only, it has no impact on the load flow.
efficiency – The efficiency class of the transformer. Informative only, it has no impact on the load flow.
cooling – The cooling class of the transformer according to IEC 60076 (ONAN, ONAF, etc.). Informative only, it has no impact on the load flow. The cooling class is defined by IEC 60076 parts 2, 11 and 15.
insulation – The transformer insulation technology (dry-type, liquid-immersed, gas-filled). Informative only, it has no impact on the load flow.

Returns:

The corresponding transformer parameters object.

Example usage:

# DSS command: `New transformer.LVTR Buses=[sourcebus, A.1.2.3] Conns=[delta wye] KVs=[11, 0.4] KVAs=[250 250] %Rs=0.00 xhl=2.5 %loadloss=0`
tp = rlf.TransformerParameters.from_open_dss(
    id="dss-tp",
    conns=("delta", "wye"),
    kvs=(11, 0.4),
    kvas=(250, 250),  # alternatively pass a scalar `kvas=250`
    leadlag="ansi",  # (Dyn1 or Yd1) or "euro" (Dyn11 or Yd11)
    xhl=2.5,
    loadloss=0,
    noloadloss=0,  # default value used in OpenDSS
    imag=0,  # default value used in OpenDSS
    rs=0,  # redundant with `loadloss=0`
)

Create a TransformerParameters object using the results of open-circuit and short-circuit tests.

Parameters:

id – A unique ID of the transformer parameters, typically its canonical name.
vg –
The vector group of the transformer.

For three-phase transformers, Dyn11 denotes a delta-wye connection with -30° phase displacement. Allowed windings are D for delta, Y for wye, Z for zigzag.

For single-phase transformers, Ii0 denotes a normal in-phase connection and Ii6 denotes an inverted connection.

For center-tapped transformers, Iii0 denotes a normal in-phase connection and Iii6 denotes an inverted connection.
uhv – Rated phase-to-phase voltage of the HV side (V).
ulv – Rated no-load phase-to-phase voltage of the LV side (V).
sn – The nominal power of the transformer (VA).
p0 – Losses during open-circuit test (W).
i0 – Current during open-circuit test (%).
psc – Losses during short-circuit test (W).
vsc – Voltages on LV side during short-circuit test (%).
fn – The nominal frequency of the transformer (Hz). Default is None. The frequency is not currently used in the transformer model as the transformer parameters already in Ohm and Siemens. It is only used when converting the transformer parameters to other formats, like PowerFactory.
manufacturer – The name of the manufacturer for the transformer. Informative only, it has no impact on the load flow. It is filled automatically when the parameters when imported from the catalogue.
range – The product range for the transformer as defined by the manufacturer. Informative only, it has no impact on the load flow. It is filled automatically when the parameters when imported from the catalogue.
efficiency – The efficiency class of the transformer. Informative only, it has no impact on the load flow. It is filled automatically when the parameters are imported from the catalogue. The efficiency class used in the catalogue follows the Eco-Design requirements as defined by the EN 50629 standard.
cooling – The cooling class of the transformer according to IEC 60076 (ONAN, ONAF, etc.). Informative only, it has no impact on the load flow. The cooling class is defined by IEC 60076 parts 2, 11 and 15.
insulation – The transformer insulation technology (dry-type, liquid-immersed, gas-filled). Informative only, it has no impact on the load flow.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) → 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(all: bool = False) → DataFrame: Get the catalogue data.

Build a transformer parameters from one in the catalogue.

Parameters:

name – The name of the transformer to get from the catalogue. It can be a regular expression. The name is subject to change when the catalogue is updated. Prefer using the other filters.
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.
cooling – The cooling class of the transformer to get (ONAN, ONAF, etc.). See also TransformerCooling.
insulation – The insulation technology of the transformer to get (dry-type, liquid-immersed, gas-filled). See also TransformerInsulation.
vg – The vector group of the transformer to get. It can be a regular expression.
sn – The nominal power of the transformer to get.
uhv – The rated phase-to-phase voltage of the HV side of the transformer to get.
ulv – The rated no-load phase-to-phase voltage of the LV side of the transformer to get.
fn – The nominal frequency of the transformer to get.
id – A unique ID for the created transformer parameters object (optional). If None (default), the id of the created object will be its name in the catalogue. Note that this parameter is not used in the data filtering.

Returns:

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

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:

name – An optional name 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.
cooling – An optional cooling class to filter the output (ONAN, ONAF, etc.). See also TransformerCooling.
insulation – An optional transformer insulation technology to filter the output (dry-type, liquid-immersed, gas-filled). See also TransformerInsulation.
vg – An optional vector group of the transformer. It can be a regular expression.
sn – An optional nominal power of the transformer to filter the output.
uhv – An optional rated high voltage to filter the output.
ulv – An optional rated no-load low voltage to filter the output.
fn – An optional nominal frequency to filter the output.

Returns:

The catalogue data as a dataframe.

classmethod extract_windings(vg: str) → tuple[str, str, int]

Extract the windings and phase displacement from a given vector group

Parameters:

vg –

The vector group of the transformer.

For three-phase transformers, Dyn11 denotes a delta-wye connection with -30° phase displacement. Allowed windings are D for delta, Y for wye, Z for zigzag.

For single-phase transformers, Ii0 denotes a normal in-phase connection and Ii6 denotes an inverted connection.

For center-tapped transformers, Iii0 denotes a normal in-phase connection and Iii6 denotes an inverted connection.

Returns:

The HV winding, the LV winding, and the phase displacement.

id

classmethod from_json(path: StrPath, *, include_results: bool = True) → Self

Construct an element from a JSON file created with to_json().

Note

Parameters:

path – The path to the network data file.
include_results – If True (default) and the results of the load flow are included in the file, the results are also loaded into the element.

Returns:

The constructed element.

to_dict(*, include_results: bool = True) → JsonDict

Convert the element to a dictionary.

Parameters:: include_results – 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.

to_json(path: StrPath, *, include_results: bool = True) → Path

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 – The path to the output file to write the network to.
include_results – If True (default), the results of the load flow are included in the JSON file. If no results are available, this option is ignored.

Returns:

The expanded and resolved path of the written file.

results_to_dict(full: bool = False) → JsonDict

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 – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.

results_to_json(path: StrPath, *, full: bool = False) → Path

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 – The path to the output file to write the results to.
full – 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.

Returns:

The expanded and resolved path of the written file.

class Transformer(id: Id, bus_hv: roseau.load_flow.models.buses.Bus, bus_lv: roseau.load_flow.models.buses.Bus, *, parameters: roseau.load_flow.models.transformer_parameters.TransformerParameters, tap: float = 1.0, phases_hv: str | None = None, phases_lv: str | None = None, connect_neutral_hv: bool | None = None, connect_neutral_lv: bool | None = None, max_loading: float | Q_[float] = 1, geometry: shapely.geometry.base.BaseGeometry | None = None)

Bases: roseau.load_flow.models.branches.AbstractBranch[TransformerSide, roseau.load_flow_engine.cy_engine.CyTransformer]

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 transformers.
bus_hv – Bus to connect the HV side of the transformer.
bus_lv – Bus to connect the LV side 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.
phases_hv – The phases of the HV side 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 vector group and the connected bus.
phases_lv – The phases of the LV side of the transformer. Similar to phases_hv.
connect_neutral_hv – Specifies whether the element’s neutral on the HV side should be connected to the HV bus’s neutral or left floating. By default, the elements’s neutral is connected when the bus has a neutral. If the bus does not have a neutral, the element’s neutral is left floating by default. To override the default behavior, pass an explicit True or False.
connect_neutral_lv – Similar to connect_neutral_hv but for the LV side.
max_loading – The maximum loading of the transformer (unitless). It is used with the sn of the TransformerParameters to compute the max_power(), res_loading() and res_violated() of the transformer.
geometry – The geometry of the transformer.

element_type: Final = 'transformer': The type of the element. It is a string like "load" or "line" etc.

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 HV side of center-tapped transformer)
P-P-N: "abn", "bcn", "can" (LV side of center-tapped transformer)

property tap: float: The tap of the transformer, for example 1.02.

property parameters: roseau.load_flow.models.transformer_parameters.TransformerParameters: The parameters of the transformer.

property max_loading: Q_[float]: The maximum loading of the transformer (unitless)

property side_hv: TransformerSide: The HV side of the transformer.

property side_lv: TransformerSide: The LV side of the transformer.

property bus_hv: roseau.load_flow.models.buses.Bus: The bus on the high voltage side of the transformer.

property bus_lv: roseau.load_flow.models.buses.Bus: The bus on the low voltage side of the transformer.

property phases_hv: str: The phases of the high voltage side of the transformer.

property phases_lv: str: The phases of the low voltage side of the transformer.

property has_floating_neutral_hv: bool: Does this transformer have a floating neutral on the HV side?

property has_floating_neutral_lv: bool: Does this transformer have a floating neutral on the LV side?

property sn: Q_[float]: The nominal power of the transformer (VA).

property max_power: Q_[float]: The maximum power loading of the transformer (in VA).

property res_loading: Q_[float]: Get the loading of the transformer (unitless).

property res_power_losses: Q_[complex]: Get the total power losses in the transformer (in VA).

property res_violated: bool: Whether the transformer power loading exceeds its maximal loading.

geometry

property side1: _Side_co: The first side of the branch.

property side2: _Side_co: The second side 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: roseau.load_flow.models.buses.Bus: The first bus of the branch.

property bus2: roseau.load_flow.models.buses.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) → Self

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

Note

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.

is_multi_phase: Final = True: Is the object multi-phase?

property network: _N_co | None: Return the network the element belong to (if any).

id

classmethod from_json(path: StrPath, *, include_results: bool = True) → Self

Construct an element from a JSON file created with to_json().

Note

Parameters:

path – The path to the network data file.
include_results – If True (default) and the results of the load flow are included in the file, the results are also loaded into the element.

Returns:

The constructed element.

to_dict(*, include_results: bool = True) → JsonDict

Convert the element to a dictionary.

Parameters:: include_results – 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.

to_json(path: StrPath, *, include_results: bool = True) → Path

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 – The path to the output file to write the network to.
include_results – If True (default), the results of the load flow are included in the JSON file. If no results are available, this option is ignored.

Returns:

The expanded and resolved path of the written file.

results_to_dict(full: bool = False) → JsonDict

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 – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.

results_to_json(path: StrPath, *, full: bool = False) → Path

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 – The path to the output file to write the results to.
full – 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.

Returns:

The expanded and resolved path of the written file.