Version 0.14.0

Release notes for Roseau Load Flow version 0.14.0.

This version requires Python 3.12+. It introduces several new features, improvements, bug fixes as well as the removals of deprecated functionality and support for older dependency versions.

Plotting Improvements

This release includes major improvements and adds many new features to the plotting module.

Voltage Profile Plotting

The new function rlf.plotting.voltage_profile plots the voltage profile of a network. This function returns an object with plot_matplotlib() and plot_plotly() methods to create plots using either Matplotlib or Plotly.

Contributed in PR 429 and PR 424

Plotting Results on an Interactive Map

The new function rlf.plotting.plot_results_interactive_map plots a network with load flow results on an interactive map. This function works similarly to rlf.plotting.plot_interactive_map, but colors the buses according to their voltage levels and the lines and transformers according to their loading levels. It also include the results in the tooltips and popups of the network elements.

Contributed in PR 426

Improvements to Interactive Map Styles

The rlf.plotting.plot_interactive_map function has been improved with several style changes to visually distinguish different voltage levels, line types, and network elements.

• Different voltage levels are represented with different marker sizes and line widths
  • Nominal voltages are used to determine the voltage levels automatically (HV, MV, LV). If nominal voltages are not available, they are inferred from the transformers and sources
• Underground lines are dashed while other lines are solid including lines with unknown line type
• Transformers are represented with a square icon with a divider in the middle and with both HV and LV buses information in the tooltip and popup
• Sourcers are represented with a bigger square icon

Note that the markers of buses, transformers and sources now use the folium.DivIcon icon which means the style function must now return a style dictionary of the form {'html': ...} for these elements.

The function also gained the fit_bounds parameter that, when set to True (default), causes the bounds of the map to be automatically adjusted using folium.FitOverlays to fit the network elements.

Contributed in PR 418

LV Line Parameters in the Catalogue

This release adds several low voltage (LV) line parameters to the line catalogue. LV line parameters include a neutral conductor and generate 4x4 matrices by default. You can create an LV line parameter using its name from the catalogue, e.g. rlf.LineParameters.from_catalogue("U_AL_3x150+70"). All added LV lines parameters have a name in the format <Type>_<Material>_3x<PhaseSection>+<NeutralSection>. You can get all added LV lines with the following regular expression:

rlf.LineParameters.get_catalogue(r"^[UOT]_[A-Z]+_3x(\d+)\+(\d+(?:\.\d+)?)$")

Contributed in PR 434

Optional Neutral Elimination When Converting Line Parameters to Symmetrical Components

When calling the to_sym method of rlf.LineParameters, you can now pass eliminate_neutral=True to optionally eliminate the neutral conductor using Kron's reduction. This is useful when converting the line parameters to other software that do not support neutral conductors like pandapower. Converting to software that support neutral conductors like PowerFactory should not eliminate the neutral conductor.

Additionally, the new function rlf.converters.kron_reduction performs Kron reduction on any nxn matrix reducing it to an (n-1)x(n-1) matrix by eliminating the last row and column.

Contributed in PR 436

Removal of Deprecated Functionality

The following deprecated functionality has been removed.

• The side parameter of rlf.GroundConnection, rlf.plotting.plot_voltage_phasors and rlf.plotting.plot_symmetrical_voltages is removed. Pass a branch side directly instead (e.g. rlf.GroundConnection(ground=ground, element=transformer.side_hv)).
• The potentials attribute and constructor parameter of Bus is removed. Use initial_potentials instead.
• The bus of a disconnected load or source no longer returns None. Use the new is_disconnected property to check if the load or source is disconnected.
• The phase parameter of rlf.PotentialRef is removed. Use phases instead.
• The res_voltages_hv and res_voltages_lv attributes of rlf.Transformer are removed. Use <side>.res_voltages instead.
• Deprecated names in rlf.constants, rlf.types and rlf.sym modules are removed.
• Deprecated modules in the rlf.utils package are removed. This package is for internal use only and should not be considered stable.

Contributed in PR 425

Dropping Support for Older Python and Dependency Versions

roseau-load-flow version 0.14.0 requires Python 3.12 or newer. Additionally, the minimum supported versions of some dependencies have been bumped as per SPEC-0.

The minimum supported versions of required dependencies are now:

• certifi>=2023.5.7
• geopandas>=1.0.0
• numpy>=1.21.5
• pandas>=1.4.0
• numpy>=2.0.0
• pandas>=2.1.0
• pint>=0.21.0
• platformdirs>=4.0.0
• pyproj>=3.3.0
• roseau-load-flow-engine>=0.19.0
• shapely>=2.0.0
• typing-extensions>=4.6.2

Contributed in PR 419 and PR 420

Miscellaneous Improvements and Bug Fixes

• Add missing transformer tap to the edge data in the graph generated by ElectricalNetwork.to_graph. Contributed in PR 427
• Improve initial voltage guesses in the Newton algorithm for networks involving delta connected sources. Contributed in PR 421
• Fix filtering catalogues using compiled regular expressions with newer versions of pandas. Contributed in PR 404
• Restore bus and layers to the layer control in the interactive map plot. This was broken in version 0.13.0. Contributed in PR 413

What's Changed

• ENH: Add the tombi tool by @benoit9126 in #410
• [single] Performance improvements of setters by @Saelyos in #411
• Bump actions/setup-python from 5 to 6 by @dependabot[bot] in #412
• Restore bus and line in interactive map layer control by @alihamdan in #413
• Bump astral-sh/setup-uv from 6 to 7 by @dependabot[bot] in #414
• Bump actions/upload-artifact from 4 to 5 by @dependabot[bot] in #415
• Replace mention of entire french network by representative networks by @alihamdan in #416
• Run tests on dev and free-threaded pythons by @alihamdan in #404
• Bump actions/checkout from 5 to 6 by @dependabot[bot] in #417
• Improve interactive map plots by @alihamdan in #418
• Drop support for Python 3.11 by @alihamdan in #419
• Simplify finding external modules for warnings by @alihamdan in #420
• Improve voltage propagation involving delta sources by @alihamdan in #421
• Factorize results plotting in preparation for voltage profiles by @alihamdan in #424
• Enforce some deprecations by @alihamdan in #425
• Interactive map plotting with results by @alihamdan in #426
• Add missing transformer tap to the networkx graph by @alihamdan in #427
• Make unit wrapped functions more ty friendly by @alihamdan in #428
• Add voltage profile plotting by @alihamdan in #429
• Bu...

Version 0.13.1

A small improvement in the license validation

• Fix a bug where license validation failed when the English (US) language was not installed on the system (observed on Linux).
• #408 Improve the display of C++ code error messages.

What's Changed

• Bump actions/checkout from 4 to 5 by @dependabot[bot] in #407
• ENH: Improve error message by @audreyf9712 in #408
• Version 0.13.1 by @benoit9126 in #409

Full Changelog: v0.13.0...v0.13.1

Version 0.13.0

Release notes for Roseau Load Flow version 0.13.0.

This version introduces several new features, improvements, and bug fixes.

Support for Open Switches

Pass closed=False to the Switch constructor to create an open switch. Call switch.open() to open an existing switch and switch.close() to close it. switch.closed tells if the switch is closed or not. The switch is closed by default.

Contributed in PR 389.

Sides Accessors for Branches

Access to parameters and results of branch sides has been improved by adding side accessors to branch elements.

• Transformer.side_hv and Transformer.side_lv return the high-voltage and low-voltage sides of a transformer.
• Line.side1 and Line.side2 return the from and to sides of a line.
• Switch.side1 and Switch.side2 return the from and to sides of a switch.

A side is a bus connectable element that has all common attributes of bus connectables. For example, Transformer.side_hv has the attributes bus, phases, res_currents, res_powers, res_voltages, etc.

Functions that used to accept a separate branch element and a side argument now accept a branch side element instead. Passing a branch element and a separate side argument to these functions is deprecated. These functions are rlf.GroundConnection, rlf.plotting.plot_voltage_phasors and rlf.plotting.plot_symmetrical_voltages. For example, replace rlf.GroundConnection(ground=ground, element=transformer, side="HV") by rlf.GroundConnection(ground=ground, element=transformer.side_hv) to avoid the deprecation warning.

Contributed in PR 385.

Plotting Improvements

• Add popup and search functionality to the interactive map plot and improve hover tooltips.

  The rlf.plotting.plot_interactive_map function now accepts add_tooltips, add_popups and add_search arguments to control the display of tooltips, popups and search features. These features are enabled by default.

• Fix an error in automatic zoom calculation when the whole network is on the same longitude or latitude.

Contributed in PR 395, PR 399.

Better Graph Support

In this release, the en.to_graph method has been revamped to fix several issues and improve usability.

• The method now returns a multi-graph to preserve parallel edges like two or more lines, transformers or switches between the same two buses.
• The geom attribute of nodes and edges is now a GeoJSON-like dictionary instead of a shapely geometry object. This makes the graph data JSON-serializable and compatible with pyviz plotting tools.
• The graph now includes nominal voltage and min/max voltage levels as node attributes.
• A new respect_switches parameter allows including open switches in the graph when set to False. By default, open switches are not included.

Contributed in PR 391.

External Tool Data in JSON Files

When writing an electrical network to a JSON file, it is now possible to include data specific to your tool or application. This data is stored in the tool_data attribute of the ElectricalNetwork class, which is a dictionary-like object. Any key-value pairs added to this dictionary will be saved in the JSON file when the network is saved and will be loaded back when the network is read from the file.

Contributed in PR 388.

Improved Unbalance Calculations

In earlier versions, the voltage unbalance calculation was limited to the IEC definition (Voltage Unbalance Factor, VUF). This release adds support for IEEE (Percentage Voltage Unbalance Ratio, PVUR) and NEMA (Load Voltage Unbalance Ratio, LVUR) definitions. The res_voltage_unbalance method now accepts a definition parameter which can be set to 'VUF', 'PVUR' or 'LVUR'.

Additionally, current unbalance calculations have been added for loads and sources through the res_current_unbalance method.

Contributed in PR 357.

Transformers Improvements

This release includes several improvements and bug fixes related to transformers and the transformers catalogue.

• Add HV/MV transformer models to the catalogue.

  The manufacturer names in the catalogue have been expanded to better accommodate new transformers (SE ⇾ Schneider Electric, FT ⇾ France Transfo, ...). Please update any references to the old manufacturer names in your code to use the new names.

• Add nominal frequency (fn), cooling class (cooling) and insulation type (insulation) to the TransformerParameters class.

  The cooling and insulation are described in the new enumeration types TransformerCooling and TransformerInsulation respectively. The transformers catalogue has been updated to include these new attributes.

• Improve load flow convergence for networks with step-up transformers.

  A bug that cause wrong source voltage propagation when the network contained step-up transformer has been fixed. This yields better initial guesses for the voltages of the buses and improves load flow convergence.

• Fix missing floating neutral of three-phase transformers when the bus does not have a neutral.

  When connecting a three-phase transformer with a neutral wire to a bus without a neutral, the neutral of the transformer was incorrectly removed. This has been fixed and the neutral of the transformer is now preserved and becomes floating.

• Fix minor inconsistency in transformer short-circuit parameters calculation.

  Iron losses are now ignored during the calculation of the short-circuit parameters of transformers with no open and short circuit tests data. This is consistent with the model we use if the open and short circuit tests data were available.

• Deprecate Transformer.res_voltage_hv and Transformer.res_voltage_lv properties added in the last release by mistake. The recommended way to access the voltages of transformer sides is now through the new side accessors: Transformer.side_hv.res_voltages and Transformer.side_lv.res_voltages.

Contributed in PR 355, PR 366, PR 382, PR 364, PR 371, PR 365.

Python Support and Build System Changes

This release drops support for Python 3.10 and older versions. Roseau Load Flow now requires Python 3.11 or newer.

This release also adds support for musl linux distributions and preliminary support for python 3.14 development version and for free-threaded python 3.13t and 3.14t. Full support is waiting on our dependencies to release relevant wheels.

We also switched from hatchling to uv_build as the build backend, this should not impact users following standard installation procedures.

Contributed in PR 362, PR 394, PR 393.

Other Notable Improvements and New Features

• Improve the performance of accessing network results as dataframes by up to 20% and serializing a network to a dictionary by up to 15%.

  The improvements are mostly noticeable with large networks or when performing many simulations like in a time series analysis.

  Contributed in PR 398.

• Add LineParameters.to_sym method to convert three-phase line parameters to symmetrical components. The method returns the symmetrical components: z0, z1, y0, y1, and for lines with a neutral wire: zn, zpn, yn, ypn.

  Contributed in PR 400.

• Detect and raise an error when duplicate line or transformer parameters IDs are used in the same network.

  This prevents unexpected behavior and prevents hard-to-debug issues and fixes an inconsistency in the handling of duplicate IDs as previously networks could be created with duplicate line or transformer parameters IDs but could not be saved to a JSON file.

  Contributed in PR 361.

• Rework the DGS conversion methods of the electrical network.

  Rename the from_dgs method of rlf.ElectricalNetwork to from_dgs_file and add a new from_dgs_dict method to load a network from a DGS-formatted dictionary. The old method is deprecated and will be removed in a future release. The from_dgs_file method accepts an optional encoding parameter to specify the encoding of the DGS file.

  Contributed in PR 374.

Other Notable Bug Fixes

• Fix lingering ground connections of disconnected loads and sources.

  Disconnect a ground connection of a load or source when the load or source is disconnected from the network. Add is_disconnected property to loads, sources and ground connections to check if the element is disconnected. In the future, accessing the bus of a disconnected load or source will return the original bus instead of None, use is_disconnected to check if the load or source is disconnected.

  Contributed in [PR ...

Version 0.12.0

Note

This is the last version of Roseau Load Flow to support Python 3.10.

Tip

This release also includes the modifications that are in the version 0.12.0-alpha #314.

Breaking changes

• The following columns have been renamed in ElectricalNetwork.transformers_frame:

  • bus1_id, bus2_id -> bus_hv_id, bus_lv_id
  • phases1, phases2 -> phases_hv, phases_lv

  and the following columns have been renamed in ElectricalNetwork.res_transformers:

  • current1, current2 -> current_hv, current_lv
  • potential1, potential2 -> potential_hv, potential_lv
  • voltage1, voltage2 -> voltage_hv, voltage_lv
  • power1, power2 -> power_hv, power_lv

• The ElectricalNetwork.crs now defaults to None (no CRS) instead of "EPSG:4326". The attribute is also no longer normalized to a pyproj.CRS object but is stored as is. Use CRS(en.crs) to
  always get a pyproj.CRS object.

Detailed changes

• A new experimental module named roseau.load_flow_single has been added for studying balanced three-phase systems using the simpler single-line model. This module is unstable and undocumented, use at your own risk.

• Improvements of license validation, particularly during simultaneous use of multiple threads or processes.

• #351 #332 Improved support of the network's Coordinate Reference System (CRS).

  • The CRS will now default to None (no CRS) instead of "EPSG:4326" if not provided.
  • The ElectricalNetwork.crs attribute is no longer normalized to a pyproj.CRS object.
  • The CRS can be set when creating a network with the ElectricalNetwork.from_element method.
  • The CRS is now correctly stored in the JSON file and is read when loading the network.

• #350 #349 Fix invalid transformer parameters with no leakage inductance when
  created from open and short circuit tests.

• #348 The load classes have two new properties: res_inner_currents and res_inner_powers. These are the currents and powers that flow in the inner components of the load as opposed to res_currents and res_powers that flow into the load.

• #343 #336 Warn when a line/switch connects buses with different nominal voltages.

• #341 Compute the transformer's open-circuit (no-load) and short-circuit tests results if they are not provided. TransformerParameters's i0, p0, vsc, and psc are now always available and no longer return None when the transformer is created from z2 and ym.

• #340 Improve the support for the conversion from the PowerFactory DGS format.

  • Add an option to ElectricalNetwork.from_dgs to use the element names (loc_name in DGS) as IDs. The names must be unique for each element type.
  • Read the transformer's maximum loading from the DGS file.
  • Read the bus's nominal voltage from the DGS file.
  • Fix conversion of the transformer's no-load test results.

• #339 Constant current loads are no longer allowed on a bus with a short-circuit. Previously, the load flow would fail with a singular matrix error.

• #335 Add GroundConnection class with the following features:

  • Ground connections for all terminal elements (buses, loads, sources) and all branch elements, (transformers, lines, switches). Previously only buses could be connected to ground.
  • Non-ideal (impedant) ground connections with the impedance parameter.
  • Access to the current in the ground connection with the res_current property.

  The method Ground.connect is deprecated in favor of the new class. Replace ground.connect(bus) by GroundConnection(ground=ground, element=bus). The attribute Ground.connected_buses is also deprecated in favor of GroundConnection.connected_elements.

• #331 Add voltage_type to the plot_voltage_phasors function to be able to plot the voltages in phase-to-phase or phase-to-neutral. The plot_symmetrical_voltages function now plots each sequence in a separate axes for better readability.

• #330 Add phase-to-phase (res_voltages_pp) and phase-to-neutral (res_voltages_pn) voltage results for terminal elements. Voltage unbalance results are now available for all terminal elements with the res_voltage_unbalance method.

• #328 Support floating neutrals for transformers. The Transformer class constructor now accepts optional connect_neutral_hv and connect_neutral_lv parameters to specify if the neutral is to be connected to the bus's neutral or to be left floating. By default the neutral is connected when the bus has a neutral and left floating otherwise.

• #328 The plot_voltage_phasors function and the plot_symmetrical_voltages functions now also support transformers, lines and switches.

• #325 Rename Bus.potentials to Bus.initial_potentials. The old attribute and constructor parameter are deprecated and will be removed in a future release.

• #319 #320 #321 #191 Deprecate the notion of "primary" and "secondary" sides of transformers in favor of "high-voltage" and "low-voltage" sides following the IEC 60076-1 standard. The following parameters of rlf.Transformer are deprecated and renamed:

  • bus1_id, bus2_id -> bus_hv_id, bus_lv_id
  • phases1, phases2 -> phases_hv, phases_lv

  The attributes bus1, bus2, phases1, phases2, winding1, winding2, phase_displacement are still available. They are aliases to newly added attributes bus_hv, bus_lv, phases_hv, phases_lv, whv, wlv, and clock respectively. The old attributes will NOT be removed.

  The corresponding columns in ElectricalNetwork.transformers_frame and ElectricalNetwork.res_transformers have been renamed as well. The old columns have been removed.

• #318 Implement all common and additional three-phase transformer vector groups. Notable addition is transformers with clock number 1, common in North America.

What's Changed

• Improve singular matrix error by @Saelyos in #301
• De-duplicate the documentation welcome section and fix ipython code-block by @alihamdan in #302
• Fix voltage_level network result when missing limits by @alihamdan in #303
• Move important modules to top-level by @alihamdan in #304
• Bump astral-sh/setup-uv from 4 to 5 by @dependabot in #305
• Add missing information and improve performance by @alihamdan in #306
• Make violations of lines and buses per-phase by @alihamdan in #307
• Remove the tutorials by @alihamdan in #309
• Support star and zigzag transformers with non brought out neutrals by @alihamdan in #310
• Improve line enumeration types and fix errors in Coiffier's model by @alihamdan in #311
• DOC: RTD generates sitemap by @benoit9126 in #312
• Update network files by @alihamdan in #313
• Version 0.12.0-alpha by @benoit9126 in #314
• Centralize the low-level solver code by @alihamdan in #316
• Fix the vector group regex for rlfs by @alihamdan in #317
• Implement more transformer vector groups by @alihamdan in #318
• Use HV and LV for transformers instead of primary and secondary by @alihamdan in #319
• Update the JSON format of transformers by @alihamdan in #320
• Add transformer results aliases and rename dataframes columns by @alihamdan in #321
• Add experimental namespace package roseau.load_flow_single by @alihamdan in #322
• Add branch potentials results by @alihamdan in #325
• Rename Bus.potentials to Bus.initial_potentials by @alihamdan in #326
• Support transformers with floating neutrals by @alihamdan in #328
• Rename BaseClasses to AbstractClasses end export them by @alihamdan in #329
• Add phase-to-phase and phase-to-neutral voltages by @alihamdan in #330
• Improve plotting functions by @alihamdan in #331
• Use covdefaults by @benoit9126 in #333
• Add support for impedant ground connections and grounding for terminals and branches by @alihamdan in #335
• Add single short circuits by @Saelyos in #339
• Improve DGS support by @alihamdan in #340
• Compute the transformer's tests results if not provided by @alihamdan in #341
• Warn when a line or a switch connects bus...

Version 0.12.0-alpha

A new alpha version to test the new features 🎉

• Some improvements of the underlying engine:
  • Simplify the center-tapped transformer model in order to improve the convergence speed (especially in case of a short-circuit).
  • Add the backward-forward algorithm for the single-phase transformers.
  • Improve the error message if a singular matrix is detected.
  • Build the engine using the manylinux_2_34 image for Linux distributions (previously it was manylinux_2_28).
• #311 Add French aliases to line enumeration types.
• #311 Fix TypeErrors in the LineParameters.from_coiffier_model. The error message of invalid models now indicates whether the line type or the conductor material is invalid.
• #310 #308 Support star and zig-zag windings with non-brought out neutral. In earlier versions, vector groups like "Yd11" were considered identical to "YNd11".
• #307 #296 Make line.res_violated and bus.res_violated return a boolean array indicating if the corresponding phase is violated. This is consistent with the dataframe results en.res_lines and en.res_buses_voltages. For old behavior, use line_or_bus.res_violated.any().
• #305 Add missing tap column to en.transformers_frame.
• #305 Add element_type column to en.potential_refs_frame to indicate if the potential reference is connected to a bus or a ground.
• #305 Add missing information to results_to_dict with full=True. This adds loading to lines and transformers, voltage_levels to buses, and voltages to loads and sources.
• #305 Improve the performance of res_violated of buses, lines and transformers.
• #304 Add top-level modules rlf.constants and rlf.types. The old modules in the utils package are deprecated and will be removed in a future release. The utils package is for internal use only and should not be considered stable.
• #304 Add top-level module rlf.sym for symmetrical components utilities. The sym_to_phasor, phasor_to_sym and series_phasor_to_sym functions are moved from the rlf.converters module to this module. The old functions are deprecated and will be removed in a future release.
• #303 Fix missing voltage_level in en.res_buses_voltages when the buses define nominal voltage but not voltage limits.
• #303 Add rlf.SQRT3 constant for the square root of 3. It can be useful for the conversion between phase-to-phase and phase-to-neutral voltages.
• #303 Improve the performance of some dataframe properties.
• #301 #299 Improve the error message when the Jacobian matrix contains infinite or NaN values.

What's Changed

• Improve singular matrix error by @Saelyos in #301
• De-duplicate the documentation welcome section and fix ipython code-block by @alihamdan in #302
• Fix voltage_level network result when missing limits by @alihamdan in #303
• Move important modules to top-level by @alihamdan in #304
• Bump astral-sh/setup-uv from 4 to 5 by @dependabot in #305
• Add missing information and improve performance by @alihamdan in #306
• Make violations of lines and buses per-phase by @alihamdan in #307
• Remove the tutorials by @alihamdan in #309
• Support star and zigzag transformers with non brought out neutrals by @alihamdan in #310
• Improve line enumeration types and fix errors in Coiffier's model by @alihamdan in #311
• DOC: RTD generates sitemap by @benoit9126 in #312
• Update network files by @alihamdan in #313
• Version 0.12.0-alpha by @benoit9126 in #314

Full Changelog: v0.11.0...v0.12.0-alpha

Version 0.11.0

This release adds official support for Python 3.13 and adds a new experimental backward-forward solver. 🎉

Breaking changes

• The min_voltage and max_voltage of Bus have been replaced by nominal_voltage (phase-to-phase, in V), a min_voltage_level (unitless) and a max_voltage_level (unitless).
• The type parameter of TransformerParameters constructors becomes vg for vector group. Replace type="single" by vg="Ii0" and type="center" by vg="Iii0".
• The type attribute of TransformerParameters now returns three-phase, single-phase or center-tapped. Use TransformerParameters.vg to get the vector group.
• The names of the transformers in the catalogue have been modified to add voltage levels and vector groups. Use rlf.TransformerParameters.get_catalogue() to see the updated catalogue.
• The max_current, section, insulator_type and conductor_type parameters of the LineParameters class are renamed to ampacities, sections, insulators and materials respectively. The new parameters accept arrays of values, one per conductor.
• The enumeration InsulatorType.UNKNOWN is removed. Please use None if the insulator is unknown.
• The definition of constant-current loads is modified to be the magnitudes of the currents and their phase shift from the voltages instead of the absolute phase shift. Currents should no longer be rotated by 120° to be in sync with the voltages.

Deprecations

• The enumerated classes InsulatorType and ConductorType are renamed to Insulator and Material respectively. Their old names are deprecated and will be removed in a future release.
• The deprecated method LineParameters.from_name_mv is removed.

Detailed changes

• #293 Fixed loading calculation for lines and transformers

• #291 Fixed several bugs in JSON serialization and deserialization.

• #289 #264 Improve the TransformerParameters class and the transformers catalogue

  • Add 15kV transformers to the catalogue (SE and FT)
  • Add single-phase transformers to the catalogue (Schneider Imprego)
  • Add step-up transformers to the catalogue (Cahors "Serie Jaune")
  • Use the correct LV side no-load voltage as defined in the datasheets (some 400V became 410V)
  • Revert #282 to keep the IEC 600076 names uhv and ulv for the transformer voltages.
  • Replace the type parameter of TransformerParameters constructors by vg for vector group.
  • TransformerParameters.type now returns three-phase, single-phase or center-tapped. Use TransformerParameters.vg to get vector group.
  • Modify the names of the transformers in the catalogue to add voltage levels and vector groups

• #285 #279 Add maximum loading for lines and transformers.

  • The constructors of Transformer and Line now accept a unitless max_loading parameter equal to 1 (=100%) by default.
  • The parameter max_currents of LineParameters is now called ampacities.
  • The Line class gained a new property max_currents that returns the maximal admissible currents (in Amps) for each conductor: line.max_current = line.parameters.ampacity * line.max_loading.
  • The res_violated property of Transformer and Line now take into account this max_loading.
  • The Line and Transformer classes have a new res_loading property to compute the loading of the element:
    • line.res_loading = line.res_currents / line.parameters.ampacities
    • transformer.res_loading = sum(transformer.res_powers) / transformer.parameters.sn

• #286 The deprecated method LineParameters.from_name_mv is removed.

• #283 Several changes related to the LineParameters:

  • The max_current, section, insulator_type and conductor_type parameters are renamed to max_currents, sections, insulators and materials respectively. The new parameters accept arrays of values, one per conductor.
  • The class method from_geometry now accepts several additional arguments related to the neutral (material_neutral, insulator_neutral, max_current_neutral)
  • The enumerated classes InsulatorType and ConductorType are renamed to Insulator and Material. Their old names are deprecated and will be removed in a future release.
  • The insulator UNKNOWN is removed. Please use None if the insulator is unknown.
  • The insulator NONE is added. It must be used to describe conductors without insulator.
  • The catalogue has now several additional columns related to the neutral parameters (resistance, reactance, susceptance, material, insulator, maximal current). The get_catalogue and the from_catalogue methods have been changed to accept filter on the columns (material_neutral, insulator_neutral, section_neutral)

• #281 Add official support for Python 3.13.

• #278 #280 Modify the Bus voltage limits:

  • The min_voltage and max_voltage parameters and attributes of Bus have been replaced by nominal_voltage (phase-to-phase, in V), a min_voltage_level (unitless) and a max_voltage_level (unitless).
  • Bus gained a new property res_voltage_levels that returns the voltage levels of the bus as a percentage of the nominal voltage;
  • The JSON file format also changed to take into account these changes. If a min_voltage or max_voltage existed in a file of a previous version, they are lost when upgrading the file.

• #277 Fix the definition of constant current loads to be the magnitudes of the currents and their phase shift from the voltages instead of the absolute phase shift. Currents should no longer be rotated by 120° to be in sync with the voltages.

• #276 Add a backward-forward solver (experimental).

• #275 Use uv instead of Rye as dependency manager.

• #273 Dynamically calculate the stacklevel of the first frame outside of roseau.load_flow for warnings

• #272 #271: Fix segfault when phases of a potential reference are not the same as the bus phases.

• #270 Use Rye instead of Poetry as dependency manager.

• #269 Optimize the SVG files of the documentation.

• #268 Set up ReadTheDoc to automatically compile the documentation.

• #267 Add a section in the documentation on Google Colab secrets.

What's Changed

• Activate License in Google Colab by @benoit9126 in #267
• DOC: ReadTheDoc by @benoit9126 in #268
• [DOC] Optimize svg by @benoit9126 in #269
• Use Rye intead of Poetry by @benoit9126 in #270
• Fix segfault when phases of pref are not the same as the bus by @alihamdan in #272
• Dynamically calculate the stacklevel of the first frame outside of roseau.load_flow for warnings by @alihamdan in #273
• Use uv by @benoit9126 in #275
• Backward forward by @Saelyos in #276
• Fix constant current loads definition by @alihamdan in #277
• Modify the voltage limits of buses by @benoit9126 in #280
• ENH: Python 3.13 by @benoit9126 in #281
• ENH: Rename uhv and ulv by @benoit9126 in #282
• Enhancements of LineParameters: arrays and new enumerated types by @benoit9126 in #283
• ENH: Remove the deprecated from_name_mv method by @benoit9126 in #286
• ENH: Add max_loading on lines and transformers by @benoit9126 in #285
• ENH: LineParameters contains 4x4 matrices by @benoit9126 in #287
• Revert "ENH: LineParameters contains 4x4 matrices" by @alihamdan in #288
• ENH: factorize some code by @benoit9126 in #290
• Add more vector groups and more transformers to the catalogue by @alihamdan in #289
• Fix bugs in JSON serialization by @alihamdan in #291
• Bump astral-sh/setup-uv from 3 to 4 by @dependabot in #292
• Update documentation, fix lines and transformers loading by @alihamdan in #293
• DOC: Download LFS files to build the documentation on ReadTheDoc by @benoit9126 in #295
• Version 0.11.0 by @benoit9126 in #294

Full Changelog: v0.10.0...v0.11.0

Version 0.10.0

A lot of improvements 🎉

Important

There is a main breaking change in this version. The constructor of the class ElectricalNetwork has changed:

• it accepts keyword arguments only.
• it accepts the arguments lines, transformers and switches in replacement of the argument branches.
• As a consequence,
  • the results method res_branches has been removed. Please use res_lines, res_transformers
    and res_switches methods instead.
  • the field branches does not exist anymore. Please use the fields lines, transformers and switches.

• A wheel for Python 3.13 is available.
• The wheels for Windows are now available. The problem was the same as the one of the
  issue 28551 of the Matplotlib repository.
• #237 Improvements of the Sphinx configuration.
• #262 Raise a proper error when a transformer is defined with null impedance.
• #259 The cache of the license object was not reset after the activation of a new license key.
• #258 #261 #263 Add basic plotting functionality in the new roseau.load_flow.plotting
  module. The plot_interactive_map function plots an electrical network on an interactive map using
  the folium library and the plot_voltage_phasors function plots the voltage phasors of a bus, load
  or source in the complex plane. The revamped plotting section of the documentation demonstrates the
  plotting functionalities available in Roseau Load Flow with examples.
• #258 The documentation gained a new "advanced" section with a page on floating neutrals
  and a page on potential references.
• #257 #252 Updates to the LineParameters class:
  • The method from_name_lv, deprecated since version 0.6, has been removed. It can be easily
    replaced by the from_geometry method.
  • The method from_name_mv is deprecated. A new method from_coiffier_model is added with the
    same functionality and more flexibility. The new method computes the ampacity of the line based
    on Coiffier's model and works with different numbers of phases.
• #256 #250:
  • Accept scalar values for the powers, currents, impedances parameters of the load classes.
  • Add rlf.PositiveSequence, rlf.NegativeSequence and rlf.ZeroSequence vectors for easier
    creation of balanced quantities.
• #255 Update the figures of loads and of voltage sources in the documentation to be compliant with the work
  of #249.
• #254 #251 Allow passing multiple phases to potential references. The phase
  attribute of the PotentialRef is replaced by phases.
• #249 #248 Accept scalar values for the voltages parameter of the VoltageSource class.
• #247 Add connect_neutral parameter to the loads and sources constructor to specify if the
  neutral is to be connected to the bus's neutral or to be left floating. This allows loads connected
  to the same bus to have different neutral connections. The default behavior remains the same as
  before where the neutral is connected when the bus has a neutral and floating otherwise.
• #246 Improvements to the rlf.converters module:
  • Fix series_phasor_to_sym function with series that have different phases per element.
  • Make calculate_voltages take array-like potentials.
  • Improve typing of several functions.
• #245 #244 Fix the LineParameters.from_geometry method to not crash when passed
  unknown insulator type or None.
• Add res_voltages to the VoltageSource class for symmetry with the other elements.
  res_voltages is always equal to the supplied voltages for a voltage source.
• #243 Fix cross-sectional area of DGS line types created from line elements and special case
  invalid PwF line geographical coordinates table.
• #240 Add tests for switches imported from DGS and improve warning and error messages.
• #235 BREAKING CHANGE: The constructor of the class ElectricalNetwork has changed:
  • it accepts keyword arguments only.
  • it accepts the arguments lines, transformers and switches in replacement of the argument branches.
  • As a consequence,
    • the results method res_branches has been removed. Please use res_lines, res_transformers
      and res_switches methods instead.
    • the field branches does not exist anymore. Please use the fields lines, transformers and switches.
• #235 Move the Switch class into its own file roseau/load_flow/models/switches.py.
• #235 #239 The JSON file format number is upgraded to the version 2. All the files in version 0 or 1
  can still be read. Please upgrade them manually using the following code:

  path = "my_json_file.json"
  ElectricalNetwork.from_json(path).to_json(path)

• #235 The method results_to_dict now accepts the keyword-only argument full which allows the export of all
  the results of an element.
• #235 Solve a bug concerning the accessors to the flexible powers result of flexible power loads. An unwanted
  error was raised.
• #235 Replace the occurrences of the str.find method by the str.index function.
• #235 The method to_graph of the class ElectricalNetwork now retrieves a graph with additional data store
  in the edges depending on the edge type: line, transformer or switch.
• #242 Add optional data to the TransformerParameters class: manufacturer, efficiency and range.
• #242 Fixed a bug in the unit of q_min and q_max in the constructor of FlexibleParameter.
• #242 Add equality operator for the classes FlexibleParameter, Control and Projection.

Version 0.9.1

Several improvements to better support importing PowerFactory models.

• #231 Add LineParameters.from_power_factory and TransformerParameters.from_power_factory
  methods to easily import PowerFactory lines and transformer models into Roseau Load Flow.

• #230 Improve the algorithm for assigning potential references for DGS networks.

• #229 Several fixes and improvements to the PowerFactory import:

  • Update the "Export Definition Folder" bundled with Roseau Load Flow as a pfd file;
  • Support lines with missing type ID. This is the case when the TypLne objects are inherited
    from an external library in PowerFactory and not included in the project being exported; A
    LineParameters object is automatically created for these lines;
  • Support "General Load (ElmLod)" elements;
  • Preserve Geometry information on buses and branches;
  • Improve handling of phases of several elements. Previously, phases were hard-coded.
  • Fix the unit of the power of static generators;
  • Fix the re-sizing of the matrices of line types without neutral elements;
  • Fix the total power of "MV Loads (ElmLodmv)" to take into account its generation power;
  • Fix all loads to no longer ignore the scale factor of the power;
  • Fix the sign of the reactive power of MV and LV loads
  • Fix the ground connection to the source bus
  • And many more...

Please refer to the Data Exchange page for more information.

Note

Windows binaries (wheels) are temporarily unavailable since version 0.9.0. If you need them, please open an issue on GitHub.

What's Changed

• Several fixes and improvements to DGS support by @alihamdan in #229
• Improve asssigning of potential refs in DGS networks by @alihamdan in #230
• Add from_power_factory methods to parameters classes by @alihamdan in #231
• Version 0.9.1 by @benoit9126 in #233

Full Changelog: v0.9.0...v0.9.1

Version 0.9.0

A lot of improvements 🎉 !

• #227 Sources and loads are now allowed to have floating neutrals. This means that a load/source
  with phases="abcn" can now be connected to a bus with phases="abc".
• #225 The calculate_voltages function now accepts and return pint quantities.
• MacOS wheels for roseau-load-flow-engine are now published on PyPI. This means that pip install roseau-load-flow
  should now work on macOS.
• Added support for running in Google Colab documents.
• Fixed a bug in license checks caching on Windows.
• Added support for Numpy 2.0.
• #222 #223 from_catalogue() methods of the electrical network and transformer
  and line parameters now perform "full match" comparison on textual inputs. If you need the old
  behavior, use regular expression wild cards .* in the input string.
• #220 #221 Add LineParameters.from_open_dss and TransformerParameters.from_open_dss methods to
  easily import OpenDSS lines and transformer models into Roseau Load Flow. More information is
  available in the documentation of these methods.
• #210 #219 Add a parameter to LineParameters.from_catalogue to choose the number
  of phases of the created line parameters object.
• #218 Add Transformer.res_power_losses to get the total power losses in a transformer.
• #217 Add an ID override to TransformerParameters.from_catalogue similar to
  LineParameters.from_catalogue.
• #216 #217 BREAKING CHANGE: Rename the id parameter of TransformerParameters
  catalogue methods to name to be consistent with LineParameters.
  If you call these methods by keyword arguments, make sure to update your usage of
  TransformerParameters.from_catalogue(id="xxx") to TransformerParameters.from_catalogue(name="xxx").
• #212 BREAKING CHANGE: Modify the constructor of TransformerParameters to take the z2
  and ym parameters directly instead of the open and short circuit tests parameters. You can still
  create an object from these tests using the from_open_and_short_circuit_tests constructor. This
  change comes with other changes to TransformerParameters, notably:
  • The z2, ym, k, and orientation are now always available as attributes on the instance
  • The to_zyk method is deprecated in favour of the direct attribute access on the instance. This
    method will be removed in a future version
  • The parameters i0, p0, psc, and vsc are now optional. They return None for instances
    created using z2 and ym directly
  • The JSON representation of TransformerParameters has changed, but it is still compatible with
    the old representation.

What's Changed

• Modify the TransformerParameters constructor by @benoit9126 in #212
• Modify TransformerParameters from_catalogue method by @alihamdan in #217
• Add Transformer.res_power_losses by @alihamdan in #218
• Allow users to specify nb phases of line parameters from catalogue by @alihamdan in #219
• Add from_open_dss method to line and transformer parameters by @alihamdan in #221
• Fix from_catalogue textual match with literal string inputs by @alihamdan in #223
• Update the docs by @alihamdan in #224
• Make calculate_voltages unit aware by @alihamdan in #225
• Add a page about data exchange to the docs by @alihamdan in #226
• Allow floating neutrals for loads and sources by @alihamdan in #227
• Version 0.9.0 by @benoit9126 in #228

Full Changelog: v0.8.1...v0.9.0

Version 0.8.1

A correction and documentation improvement:

• #214 Solve a bug in the engine when using delta connected flexible loads.
• #213 Better detection of poorly connected elements as described in #209. It raises a proper error
  message.
• #211 Several improvements of the documentation:
  • Add Open Graph metadata to the documentation page.
  • Error on the susceptance unit in the tables of the LineParameters' catalogue.
  • Replot the networks of the catalogue (add a H1 title, use the Raleway font, only plot the lines to add their
    parameters id in the tooltip)

What's Changed

• Improvements of the documentation (opengraph, networks' catalogue plotting) by @benoit9126 in #211
• Poorly connected elements by @Saelyos in #213
• Version 0.8.1 by @benoit9126 in #215

Full Changelog: v0.8.0...v0.8.1