Roseau-load-flow

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

- {gh-issue}`214` Solve a bug in the engine when using delta connected flexible loads.
- {gh-pr}`213` Better detection of poorly connected elements as described in {gh-issue}`209`. It raises a proper error
message.
- {gh-pr}`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)