Roseau-load-flow

{note}
This is the last version of _Roseau Load Flow_ to support Python 3.10.


{seealso}
This release also includes the modifications that are in the [version 0.12.0-alpha](version-0120-alpha).


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.
- {gh-pr}`351` {gh-issue}`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.
- {gh-pr}`350` {gh-issue}`349` Fix invalid transformer parameters with no leakage inductance when
created from open and short circuit tests.
- {gh-pr}`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.
- {gh-pr}`343` {gh-issue}`336` Warn when a line/switch connects buses with different nominal voltages.
- {gh-pr}`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`.
- {gh-pr}`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.
- {gh-pr}`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.
- {gh-pr}`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`.

- {gh-pr}`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.
- {gh-pr}`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.
- {gh-pr}`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.
- {gh-pr}`328` The `plot_voltage_phasors` function and the `plot_symmetrical_voltages` functions now
also support transformers, lines and switches.
- {gh-pr}`325` Rename `Bus.potentials` to `Bus.initial_potentials`. The old attribute and constructor
parameter are deprecated and will be removed in a future release.
- {gh-pr}`319` {gh-pr}`320` {gh-pr}`321` {gh-issue}`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`, `bus2` -> `bus_hv`, `bus_lv`
- `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.

- {gh-pr}`318` Implement all common and additional three-phase transformer vector groups. Notable
addition is transformers with clock number 1, common in North America.

- 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`).
- {gh-pr}`311` Add French aliases to line enumeration types.
- {gh-pr}`311` Fix `TypeError`s in the `LineParameters.from_coiffier_model`. The error message of
invalid models now indicates whether the line type or the conductor material is invalid.
- {gh-pr}`310` {gh-issue}`308` Support star and zig-zag windings with non-brought out neutral. In
earlier versions, vector groups like "Yd11" were considered identical to "YNd11".
- {gh-pr}`307` {gh-issue}`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()`.
- {gh-pr}`305` Add missing `tap` column to `en.transformers_frame`.
- {gh-pr}`305` Add `element_type` column to `en.potential_refs_frame` to indicate if the potential
reference is connected to a bus or a ground.
- {gh-pr}`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.
- {gh-pr}`305` Improve the performance of `res_violated` of buses, lines and transformers.
- {gh-pr}`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.
- {gh-pr}`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.
- {gh-pr}`303` Fix missing `voltage_level` in `en.res_buses_voltages` when the buses define nominal
voltage but not voltage limits.
- {gh-pr}`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.
- {gh-pr}`303` Improve the performance of some dataframe properties.
- {gh-pr}`301` {gh-issue}`299` Improve the error message when the Jacobian matrix contains infinite
or NaN values.

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

- {gh-pr}`293` Fixed `loading` calculation for lines and transformers
- {gh-pr}`291` Fixed several bugs in JSON serialization and deserialization.
- {gh-pr}`289` {gh-issue}`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 {gh-pr}`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

- {gh-pr}`285` {gh-issue}`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`

- {gh-pr}`286` The deprecated method `LineParameters.from_name_mv` is removed.
- {gh-pr}`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`)

- {gh-pr}`281` Add official support for Python 3.13.
- {gh-issue}`278` {gh-pr}`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.

- {gh-pr}`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.
- {gh-pr}`276` Add a backward-forward solver (experimental).
- {gh-pr}`275` Use [uv](https://docs.astral.sh/uv/) instead of [Rye](https://rye.astral.sh/) as dependency manager.
- {gh-pr}`273` Dynamically calculate the stacklevel of the first frame outside of `roseau.load_flow` for warnings
- {gh-pr}`272` {gh-issue}`271`: Fix segfault when phases of a potential reference are not the same as the bus phases.
- {gh-pr}`270` Use [Rye](https://rye.astral.sh/) instead of [Poetry](https://python-poetry.org/) as dependency manager.
- {gh-pr}`269` Optimize the SVG files of the documentation.
- {gh-pr}`268` Set up ReadTheDoc to automatically compile the documentation.
- {gh-pr}`267` Add a section in the documentation on Google Colab secrets.

- 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](https://github.com/matplotlib/matplotlib/issues/28551) of the Matplotlib repository.
- {gh-pr}`237` Improvements of the Sphinx configuration.
- {gh-pr}`262` Raise a proper error when a transformer is defined with null impedance.
- {gh-pr}`259` The cache of the license object was not reset after the activation of a new license key.
- {gh-pr}`258` {gh-pr}`261` {gh-pr}`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.
- {gh-pr}`258` The documentation gained a new "advanced" section with a page on floating neutrals
and a page on potential references.
- {gh-pr}`257` {gh-issue}`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.
- {gh-pr}`256` {gh-issue}`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.
- {gh-pr}`255` Update the figures of loads and of voltage sources in the documentation to be compliant with the work
of {gh-pr}`249`.
- {gh-pr}`254` {gh-issue}`251` Allow passing multiple phases to potential references. The `phase`
attribute of the `PotentialRef` is replaced by `phases`.
- {gh-pr}`249` {gh-issue}`248` Accept scalar values for the `voltages` parameter of the `VoltageSource` class.
- {gh-pr}`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.
- {gh-pr}`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.
- {gh-pr}`245` {gh-issue}`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.
- {gh-pr}`243` Fix cross-sectional area of DGS line types created from line elements and special case
invalid PwF line geographical coordinates table.
- {gh-pr}`240` Add tests for switches imported from DGS and improve warning and error messages.
- {gh-pr}`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`.
- {gh-pr}`235` Move the `Switch` class into its own file `roseau/load_flow/models/switches.py`.
- {gh-pr}`235` {gh-pr}`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:
python
path = "my_json_file.json"
ElectricalNetwork.from_json(path).to_json(path)

- {gh-pr}`235` The method `results_to_dict` now accepts the keyword-only argument `full` which allows the export of all
the results of an element.
- {gh-pr}`235` Solve a bug concerning the accessors to the flexible powers result of flexible power loads. An unwanted
error was raised.
- {gh-pr}`235` Replace the occurrences of the `str.find` method by the `str.index` function.
- {gh-pr}`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.
- {gh-pr}`242` Add optional data to the `TransformerParameters` class: manufacturer, efficiency and range.
- {gh-pr}`242` Fixed a bug in the unit of `q_min` and `q_max` in the constructor of `FlexibleParameter`.
- {gh-pr}`242` Add equality operator for the classes `FlexibleParameter`, `Control` and `Projection`.

{note}
The wheels for Windows are temporarily unavailable anymore. If you need them, please post an issue on GitHub.


- {gh-pr}`231` Add `LineParameters.from_power_factory` and `TransformerParameters.from_power_factory`
methods to easily import PowerFactory lines and transformer models into Roseau Load Flow.
- {gh-pr}`230` Improve the algorithm for assigning potential references for DGS networks.
- {gh-pr}`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 the 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...

- {gh-pr}`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"`.
- {gh-pr}`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.
- {gh-issue}`222` {gh-pr}`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.
- {gh-issue}`220` {gh-pr}`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.
- {gh-issue}`210` {gh-pr}`219` Add a parameter to `LineParameters.from_catalogue` to choose the number
of phases of the created line parameters object.
- {gh-pr}`218` Add `Transformer.res_power_losses` to get the total power losses in a transformer.
- {gh-pr}`217` Add an ID override to `TransformerParameters.from_catalogue` similar to
`LineParameters.from_catalogue`.
- {gh-issue}`216` {gh-pr}`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")`.
- {gh-pr}`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.