Transformers¶

Definition¶

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

Transformer parameters¶

Transformers are modeled with the following parameters:

\(U_{1,\mathrm{nom.}}\): the phase-to-phase nominal voltage of the high voltages side (in V). This parameter is called uhv in the code.
\(U_{2,\mathrm{nom.}}\): the phase-to-phase nominal voltage of the low voltages side (in V). This parameter is called ulv in the code.
\(S_{\mathrm{nom.}}\): the nominal power of the transformer (in VA). This parameter is called sn in the code.
\(Z_2\): the series impedance located at the secondary side of the transformer. It represents non-ideal transformer losses due to winding resistance and leakage reactance.
\(Y_m\): the magnetizing admittance located at the primary side of the transformer. It represents non-ideal transformer losses due to core magnetizing inductance and iron losses.

\(Z_2\) and \(Y_m\) parameters come from open-circuit and short-circuit tests. They can be obtained using the following tests results:

\(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.

For three-phase transformers, the windings configuration is also required. See the dedicated page of three-phase transformers for more details.

First, we define the following quantities:

\(i_{1,\mathrm{nom.}}=\dfrac{S_{\mathrm{nom.}}}{U_{1,\mathrm{nom.}}}\): the nominal current of the winding on the primary side of the transformer
\(i_{2,\mathrm{nom.}}=\dfrac{S_{\mathrm{nom.}}}{U_{2,\mathrm{nom.}}}\): the nominal current of the winding on the secondary side of the transformer.

Open-circuit and short-circuit tests¶

Open-circuit test¶

We note \(P_0\) the losses and \(i_1^0\) the current in the primary winding of the transformer during this test. The following values can be computed:

\[\begin{split}\begin{aligned} i_0&=100\cdot \frac{i_1^0}{i_{1,\mathrm{nom.}}} \qquad \text{(in %)} \\ S_0 &= U_0\cdot i_1^0 = U_{1,\mathrm{nom.}}\cdot (i_0\cdot i_{1,\mathrm{nom.}}) = i_0\cdot S_{\mathrm{nom.}} \qquad \text{(in VA)}\\ R_{\mathrm{iron}} &= \dfrac{U_{1,\mathrm{nom.}}^2}{P_0} \qquad \text{(in Ohm)}\\ L_{\mathrm{m}} &= \dfrac{U_{1,\mathrm{nom.}}^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¶

We note \(P_{\mathrm{sc}}\) the losses, \(U_{2,\mathrm{sc}}\) the voltage on LV side during this test. The following values can be computed:

\[\begin{split}\begin{aligned} V_{\mathrm{sc}}&= 100\cdot \frac{U_{2,\mathrm{sc}}}{U_{2,\mathrm{nom.}}} \qquad \text{(in %)} \\ Z_2&=\frac{U_{2,\mathrm{sc}}}{i_{2,\mathrm{nom.}}}=U_{2,\mathrm{sc}}\cdot\frac{U_{2,\mathrm{nom.}}}{ S_{\mathrm{nom.}}} =V_{\mathrm{sc}}\cdot\frac{U_{2,\mathrm{nom.}}^2}{S_{\mathrm{nom.}}} \qquad \text{(in Ohm)}\\ R_2&=\frac{P_{\mathrm{sc}}}{i_{2,\mathrm{nom.}}^2} = \frac{P_{\mathrm{sc}}\cdot U_{2,\mathrm{nom.}}^2}{ S_{\mathrm{nom.}}^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\]

Import from OpenDSS¶

Transformer parameters can also be created using an OpenDSS transformer parameters. Only two-winding three-phase transformers are currently supported. For more information and an example, see the TransformerParameters.from_open_dss() method.

Usage¶

To define the parameters of the transformers, use the TransformerParameters class. It takes as arguments the elements described in the previous section and converts them into the series impedance and the magnetizing admittance. The type argument of the constructor can take the following values:

"single" to model a single-phase transformer
"center" to model a center-tapped transformer
Any windings ("Dd0", "Dz6", etc.) to model a three-phase transformer.

import roseau.load_flow as rlf

# The transformer parameters for a single-phase transformer
single_phase_transformer_parameters = (
    rlf.TransformerParameters.from_open_and_short_circuit_tests(
        id="single_phase_transformer_parameters",
        type="single",  # <--- 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, "%"),
    )
)
# Alternatively, if you have z2 and ym already:
# single_phase_transformer_parameters = rlf.TransformerParameters(
#     id="single_phase_transformer_parameters",
#     type="single",
#     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"),
# )


# The transformer parameters for a three-phase transformer
three_phase_transformer_parameters = (
    rlf.TransformerParameters.from_open_and_short_circuit_tests(
        id="three_phase_transformer_parameters",
        type="Dyn11",  # <--- three-phase transformer with delta primary and wye secondary
        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, "%"),
    )
)

# The transformer parameters for a center-tapped transformer
center_tapped_transformer_parameters = (
    rlf.TransformerParameters.from_open_and_short_circuit_tests(
        id="center_tapped_transformer_parameters",
        type="center",  # <--- 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, "%"),
    )
)

A catalogue of transformer parameters is available. More details here.

Available models¶

The following transformer models are available in Roseau Load Flow:

Transformers

API Reference¶

Bases: Identifiable, JsonMixin, CatalogueMixin[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)
z2 – The series impedance located at the secondary side of the transformer.
ym – The magnetizing admittance located at the primary side of the transformer.
max_power – The maximum power loading of the transformer (VA). It is not used in the load flow.

property uhv: Quantity[float]: Phase-to-phase nominal voltages of the high voltages side (V).

property ulv: Quantity[float]: Phase-to-phase nominal voltages of the low voltages side (V).

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

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

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

property k: Quantity[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 max_power: Quantity[float] | None: The maximum power loading of the transformer (VA) if it is set.

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

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

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

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

to_zyk() → tuple[Quantity[complex], Quantity[complex], Quantity[float], float]

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

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 high voltage side.
ulv – PwF parameter utrn_l (Rated Voltage LV-Side). The rated phase to phase voltage of the transformer on the low voltage 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.
maxload – PwF parameter maxload (Max. Thermal Loading Limit). The maximum loading of the transformer in (%) of the nominal power. This parameter is defined on the transformer element (ElmTr2) in PwF instead of the transformer type (TypTr2). This is used to compute max_current and is used for violation checks.

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 (Uhv, Ulv).
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.
normhkva – OpenDSS parameter: NormHKVA. Normal maximum kVA rating for H winding (1). Usually 100 - 110% of maximum nameplate rating. This value is passed to max_current and used for violation checks.

Returns:

The corresponding transformer parameters object.

Example usage:

# DSS command: `DSSText.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="euro",  # THE ONLY OPENDSS MODEL WE CURRENTLY SUPPORT
    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.
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 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 (%)
max_power – The maximum power loading of the transformer (VA). It is not used in the load flow.

classmethod from_dict(data: dict[str, Any], *, 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() → 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.
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.
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. Note that this parameter is not used in the data filtering.

Returns:

The selected transformer. If several transformers fitting the filters are 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.
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

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

Bases: 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.

allowed_phases: Final = frozenset({'ab', 'abc', 'abcn', 'abn', 'an', 'bc', 'bcn', 'bn', 'ca', 'can', 'cn'})

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)

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

property parameters: TransformerParameters: The parameters of the transformer.

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

property res_power_losses: Quantity[complex]: Get the total power losses in 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.