roseau.load_flow.io.dgs¶

This module is not for public use.

Use the ElectricalNetwork.from_dgs method to read a network from a dgs file.

Exceptions¶

RoseauLoadFlowException

Base exception for Roseau Load Flow.

Classes¶

`RoseauLoadFlowExceptionCode`	Error codes used by Roseau Load Flow.
`AbstractBranch`	Base class of all the branches (lines, switches and transformers) of the network.
`AbstractLoad`	An abstract class of an electric load.
`Bus`	A multi-phase electrical bus.
`Element`	An abstract class of an element in an Electrical network.
`Ground`	This element defines the ground.
`LineParameters`	Parameters that define electrical models of lines.
`PotentialRef`	A potential reference.
`Transformer`	A generic transformer model.
`TransformerParameters`	Parameters that define electrical models of transformers.
`VoltageSource`	A voltage source.

Functions¶

`generate_buses`(→ None)	Generate the buses of the network.
`generate_lines`(→ None)	Generate the lines of the network.
`generate_typ_lne`(→ None)	Generate line parameters from the "TypLne" dataframe.
`generate_loads`(→ None)	Generate the loads of a given load type.
`generate_sources`(→ None)	Generate the sources of the network from External Network data.
`generate_switches`(→ None)	Generate the switches of the network.
`generate_transformers`(→ None)	Generate the transformers of the network.
`generate_typ_tr`(→ None)	Generate transformer parameters from the "TypTr2" dataframe.
`network_from_dgs`(...)	Create the electrical elements from a JSON file in DGS format.

Package Contents¶

exception RoseauLoadFlowException(msg: str, code: RoseauLoadFlowExceptionCode, *args: object)¶

Bases: Exception

Base exception for Roseau Load Flow.

Constructor of RoseauLoadFlowException.

Parameters:

msg – A text description that provides the reason of the exception and potential solution.
code – The code that identifies the reason of the exception.

class RoseauLoadFlowExceptionCode¶

Bases: roseau.load_flow._compat.StrEnum

Error codes used by Roseau Load Flow.

Initialize self. See help(type(self)) for accurate signature.

generate_buses(elm_term: DataFrame, buses: dict[Id, Bus]) → None¶

Generate the buses of the network.

Parameters:

elm_term – The “ElmTerm” dataframe containing the bus data.
buses – The dictionary to store the buses into.

generate_lines(elm_lne: DataFrame, branches: dict[Id, AbstractBranch], buses: dict[Id, Bus], sta_cubic: DataFrame, lines_params: dict[Id, LineParameters], ground: Ground) → None¶

Generate the lines of the network.

Parameters:

elm_lne – The “ElmLne” dataframe containing the line data.
branches – The dictionary to store the lines into.
buses – The dictionary of the all buses.
sta_cubic – The “StaCubic” dataframe of cubicles.
lines_params – The dictionary of all lines parameters. If the line does not define a type Id, a line parameters object will be created and stored in this dictionary.
ground – The ground object to connect to lines that have shunt components.

generate_typ_lne(typ_lne: DataFrame, lines_params: dict[Id, LineParameters]) → None¶

Generate line parameters from the “TypLne” dataframe.

Parameters:

typ_lne – The “TypLne” dataframe containing line parameters data.
lines_params – The dictionary to store the line parameters into.

generate_loads(elm_lod: DataFrame, loads: dict[Id, AbstractLoad], buses: dict[Id, Bus], sta_cubic: DataFrame, factor: float, load_type: roseau.load_flow.io.dgs.constants.PwFLoadType) → None¶

Generate the loads of a given load type.

Parameters:

elm_lod – The dataframe containing the load data.
loads – The dictionary to store the loads into.
buses – The dictionary of the all buses.
sta_cubic – The “StaCubic” dataframe of cubicles.
factor – The factor to multiply the load power (ex: 1e3 for kVA -> VA)
load_type – The type of the PwF Load: “MV” (ElmLodmv), “LV” (ElmLodLV), “General” (ElmLod), “PV” (ElmPVSys), “GenStat” (ElmGenStat).

generate_sources(elm_xnet: DataFrame, sources: dict[Id, AbstractLoad], buses: dict[Id, Bus], sta_cubic: DataFrame, elm_term: DataFrame) → None¶

Generate the sources of the network from External Network data.

Parameters:

elm_xnet – The “ElmXnet” dataframe containing the external network data.
sources – The dictionary to store the sources into.
buses – The dictionary of the all buses.
sta_cubic – The “StaCubic” dataframe of cubicles.
elm_term – The “ElmTerm” dataframe containing the bus data.

generate_switches(elm_coup: DataFrame, branches: dict[Id, AbstractBranch], buses: dict[Id, Bus], sta_cubic: DataFrame) → None¶

Generate the switches of the network.

Parameters:

elm_coup – The “ElmCoup” dataframe containing the switch data.
branches – The dictionary to store the switches into.
buses – The dictionary of the all buses.
sta_cubic – The “StaCubic” dataframe of cubicles.

generate_transformers(elm_tr: DataFrame, branches: dict[Id, AbstractBranch], buses: dict[Id, Bus], sta_cubic: DataFrame, transformers_tap: dict[Id, int], transformers_params: dict[Id, TransformerParameters]) → None¶

Generate the transformers of the network.

Parameters:

elm_tr2 – The “ElmTr2” dataframe containing the transformer data.
branches – The dictionary to store the transformers into.
buses – The dictionary of the all buses.
sta_cubic – The “StaCubic” dataframe of cubicles.
transformers_tap – The dictionary of all transformers tap positions.
transformers_params – The dictionary of all transformers parameters.

generate_typ_tr(typ_tr: DataFrame, transformers_params: dict[Id, TransformerParameters], transformers_tap: dict[Id, float]) → None¶

Generate transformer parameters from the “TypTr2” dataframe.

Parameters:

typ_lne – The “TypTr2” dataframe containing transformer parameters data.
transformers_params – The dictionary to store the transformer parameters into.
transformers_tap – The dictionary to store the tap positions of the transformers into.

class AbstractBranch(id: Id, bus1: roseau.load_flow.models.buses.Bus, bus2: roseau.load_flow.models.buses.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.

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.

Create a line parameters object from PowerFactory “TypLne” data.

Parameters:

id – A unique ID of the line parameters.
r0 – PwF parameter rline0 (AC-Resistance R0’). Zero sequence resistance in (ohms/km).
r1 – PwF parameter rline (AC-Resistance R1’). Direct sequence resistance in (ohms/km).
x0 – PwF parameter xline0 (Reactance X0’). Zero sequence reactance in (ohms/km).
x1 – PwF parameter xline (Reactance X1’). Direct sequence reactance in (ohms/km).
b0 – PwF parameter bline0 (Susceptance B0’). Zero sequence susceptance in (µS/km).
b1 – PwF parameter bline (Susceptance B’). Direct sequence susceptance in (µS/km).
rn – PwF parameter rnline (AC-Resistance Rn’). Neutral resistance in (ohms/km).
xn – PwF parameter xnline (Reactance Xn’). Neutral reactance in (ohms/km).
bn – PwF parameter bnline (Susceptance Bn’). Neutral susceptance in (µS/km).
rpn – PwF parameter rnpline (AC-Resistance Rpn’). Phase-Neutral coupling resistance in (ohms/km).
xpn – PwF parameter xnpline (Reactance Xpn’). Phase-Neutral coupling reactance in (ohms/km).
bpn – PwF parameter bnpline (Susceptance Bpn’). Phase-Neutral coupling susceptance in (µS/km).
nphase – PwF parameter nlnph (Phases). The number of phases of the line between 1 and 3. This should not count the neutral conductor.
nneutral – PwF parameter nneutral (Number of Neutrals). The number of neutrals of the line. It can be either 0 or 1.
cohl – PwF parameter cohl_ (Cable/OHL). The type of the line; ‘Cable’ or 0 mean an underground cable and ‘OHL’ or 1 mean an overhead line.
inom – PwF parameter sline or InomAir (Rated Current in ground or in air). The rated current in (kA) of the line. It is used as the maximum current for analysis of network constraint violations. Pass the sline parameter if the line is an underground cable (cohl=’Cable’) or the InomAir parameter if the line is an overhead line (cohl=’OHL’).
conductor – PwF parameter mlei (Conductor Material). The material used for the conductors. It can be one of: ‘Al’ (Aluminium), ‘Cu’ (Copper), ‘Ad’ (Aldrey AlMgSi), ‘As’ (Aluminium-Steel), ‘Ds’ (Aldrey-Steel).
insulation – PwF parameter imiso (Insulation Material). The material used for the conductor’s insulation. It can be one of ‘PVC’ (0), ‘XLPE’ (1), ‘Mineral’ (2), ‘Paper’ (3) or ‘EPR’ (4).
section – PwF parameter qurs (Nominal Cross Section). The nominal cross-sectional area of the conductors in (mm²).

Returns:

The created line parameters.

Create a line parameters object from OpenDSS “LineCode” data.

Parameters:

id – The unique ID of the line parameters.
nphases – OpenDSS parameter: NPhases. Number of phases in the line this line code represents. To create single-phase lines with a neutral pass nphases=2, for three-phase lines with a neutral nphases=4, etc.
r1 – OpenDSS parameter: R1. Positive-sequence resistance in (ohm/km).
r0 – OpenDSS parameter: R0. Positive-sequence resistance in (ohm/km).
x1 – OpenDSS parameter: X1. Positive-sequence reactance in (ohm/km).
x0 – OpenDSS parameter: X0. Positive-sequence reactance in (ohm/km).
c1 – OpenDSS parameter: C1. Positive-sequence capacitance in (nF/km).
c0 – OpenDSS parameter: C0. Positive-sequence capacitance in (nF/km).
basefreq – OpenDSS parameter: BaseFreq. Frequency at which impedances are specified (Hz). Defaults to 50 Hz.
normamps – OpenDSS parameter: NormAmps. Normal ampere limit on line (A). This is the so-called Planning Limit. It may also be the value above which load will have to be dropped in a contingency. Usually about 75% - 80% of the emergency (one-hour) rating. This value is passed to max_current and used for violation checks.
linetype – OpenDSS parameter: LineType. Code designating the type of line. Only "OH" (overhead) and "UG" (underground) are currently supported.

Returns:

The corresponding line parameters object.

Example usage:

# DSS command: `New linecode.240sq nphases=3 R1=0.127 X1=0.072 R0=0.342 X0=0.089 units=km`
lp = LineParameters.from_open_dss(
    id="linecode-240sq",
    nphases=3,  #  creates 3x3 Z,Y matrices
    r1=Q_(0.127, "ohm/km"),
    x1=Q_(0.072, "ohm/km"),
    r0=Q_(0.342, "ohm/km"),
    x0=Q_(0.089, "ohm/km"),
    c1=Q_(3.4, "nF/km"),  # default value used in OpenDSS code
    c0=Q_(1.6, "nF/km"),  # default value used in OpenDSS code
)

# DSS command: `New LineCode.16sq NPhases=1 R1=0.350, X1=0.025, R0=0.366, X0=0.025, C1=1.036, C0=0.488 Units=kft NormAmps=400`
lp = LineParameters.from_open_dss(
    id="linecode-16sq",
    nphases=1,  # creates 1x1 Z,Y matrices
    r1=Q_(0.350, "ohm/kft"),
    x1=Q_(0.025, "ohm/kft"),
    r0=Q_(0.366, "ohm/kft"),
    x0=Q_(0.025, "ohm/kft"),
    c1=Q_(1.036, "nF/kft"),
    c0=Q_(0.488, "nF/kft"),
    normamps=Q_(400, "A"),
)

classmethod catalogue_path() → Path¶: Get the path to the catalogue.

classmethod catalogue_data() → DataFrame¶: Get the catalogue data.

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. Note that this parameter is not used in the data filtering.
nb_phases – The number of phases of the line between 1 and 4, defaults to 3. It represents the size of the z_line and y_shunt matrices.

Returns:

The created line parameters.

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 PotentialRef(id: Id, element: roseau.load_flow.models.buses.Bus | roseau.load_flow.models.grounds.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

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: roseau.load_flow.models.buses.Bus, bus2: roseau.load_flow.models.buses.Bus, *, parameters: roseau.load_flow.models.transformers.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.

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)

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

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

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

property res_power_losses: Q_[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.

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

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

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

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

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

to_zyk() → tuple[Q_[complex], Q_[complex], Q_[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: JsonDict, *, include_results: bool = True) → typing_extensions.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.

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 VoltageSource(id: Id, bus: roseau.load_flow.models.buses.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 bus phases are used by default. 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 must be present in the phases of the connected bus. Multiphase sources are allowed to have a floating neutral (i.e. they can be connected to buses that don’t have a neutral).

allowed_phases: Final¶: The allowed phases for a voltage source are the same as for a bus.

property phases: str¶: The phases of the source.

property bus: roseau.load_flow.models.buses.Bus¶: The bus of the source.

property voltages: Q_[ComplexArray]¶: The voltages of the source (V).

property has_floating_neutral: bool¶: Does this source have a floating neutral?

voltage_phases() → list[str]¶: The phases of the source voltages.

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

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

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.

network_from_dgs(filename: StrPath) → tuple[dict[Id, Bus], dict[Id, AbstractBranch], dict[Id, AbstractLoad], dict[Id, VoltageSource], dict[Id, Ground], dict[Id, PotentialRef]]¶

Create the electrical elements from a JSON file in DGS format.

Parameters:: filename – name of the JSON file
Returns:: The elements of the network – buses, branches, loads, sources, grounds and potential refs.