Merge pull request #314 from RoseauTechnologies/develop

Version 0.12.0-alpha

.github/workflows/ci.yml

@@ -17,6 +17,7 @@ on:
 env:
   CI: true
   UV_SYSTEM_PYTHON: 1
+  COVERAGE_CORE: sysmon
 
 jobs:
   build:
@@ -51,7 +52,7 @@ jobs:
           git lfs prune --verify-remote
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
 
@@ -66,7 +67,7 @@ jobs:
 
       - name: Test with pytest
         run: |
-          uv run pytest -vv -n=auto --durations=25 --cov-report html --cov-config pyproject.toml roseau
+          uv run pytest -vv -n=auto --durations=25 --cov --cov-report=html roseau
         env:
           ROSEAU_LOAD_FLOW_LICENSE_KEY: ${{ secrets.ROSEAU_LOAD_FLOW_LICENSE_KEY }}
 

.pre-commit-config.yaml

@@ -11,11 +11,11 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.5.5
+    rev: 0.5.16
     hooks:
       - id: uv-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.1
+    rev: v0.8.6
     hooks:
       - id: ruff
         args: [--fix]
@@ -27,7 +27,7 @@ repos:
         files: ^doc/.*\.md$
         args: [-l 90]
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.4.1
+    rev: v3.4.2
     hooks:
       - id: prettier
         args: ["--print-width", "120"]

README.md

@@ -4,28 +4,32 @@
 ![pre-commit](https://github.com/RoseauTechnologies/Roseau_Load_Flow/actions/workflows/pre-commit.yml/badge.svg)
 [![Documentation Status](https://readthedocs.org/projects/roseau-load-flow/badge/?version=latest)](https://roseau-load-flow.readthedocs.io/en/latest/?badge=latest)
 
-_Roseau Load Flow_ is a powerful multi-phase load flow solver for unbalanced power flow analysis that
-offers:
+<!-- start rlf-pitch -->
 
-- Multi-phase, unbalanced power flow analysis
-- Performance optimized solver written in C++
+_Roseau Load Flow_ is a powerful load flow solver and static analysis tool that offers:
+
+- **Multi-phase**, **unbalanced** power flow analysis
+- A performance optimized solver written in C++
 - A catalogue of real-world transformer and line models
-- An ergonomic object-oriented Python interface
+- An ergonomic object-oriented Python interface with unit-aware quantities
 - A comprehensive documentation with code examples
 - Real-world distribution network data samples in the library (with more available on request)
 
-In addition to the following _unique_ set of features:
+In addition to the following **unique** set of features:
 
-- Support for floating neutrals for loads and sources
+- Support for _floating neutrals_ for loads and sources
 - Four-wire multi-phase modelling with no Kron's reduction, no transformations, no assumptions on the
   network topology and no implicit earthing everywhere
-- Support for flexible, voltage-dependent, loads directly in the Newton algorithm for better convergence
+- Support for **flexible**, voltage-dependent, loads directly in the Newton algorithm for better
+  convergence and stability
+
+<!-- end rlf-pitch -->
 
 This project is compatible with Python version 3.10 and newer. The
-[installation instructions](https://roseau-load-flow.roseautechnologies.com/Installation.html)
+[installation instructions](https://roseau-load-flow.roseautechnologies.com/en/latest/Installation.html)
 will guide you through the installation process. If you are new to _Roseau Load Flow_, we recommend
 you start with the
-[getting started tutorial](https://roseau-load-flow.roseautechnologies.com/usage/Getting_Started.html).
+[getting started tutorial](https://roseau-load-flow.roseautechnologies.com/en/latest/usage/Getting_Started.html).
 You can find the complete documentation at https://roseau-load-flow.roseautechnologies.com/.
 
 ## License
@@ -39,15 +43,19 @@ at [contact@roseautechnologies.com](mailto:contact@roseautechnologies.com).
 > Licenses are given free of charge for **students and teachers**. Please contact us at
 > contact@roseautechnologies.com for more information.
 
-Read more at [License](https://roseau-load-flow.roseautechnologies.com/License.html).
+Read more at [License](https://roseau-load-flow.roseautechnologies.com/en/latest/License.html).
 
 ## Network data
 
+<!-- start rlf-networks -->
+
 _Roseau Load Flow_ ships with a sample of 20 low-voltage and 20 medium-voltage feeder networks. Each
 network is provided with its summer and winter load points. At _Roseau Technologies_, we can provide
 the major part of the French medium and low voltage networks on demand. For more information, please
 contact us at contact@roseautechnologies.com.
 
+<!-- end rlf-networks -->
+
 <div align="center">
   <img alt="Catalogue of networks" src="https://github.com/RoseauTechnologies/Roseau_Load_Flow/blob/main/doc/_static/Network/Catalogue.png?raw=True" />
 </div>

doc/Changelog.md

@@ -17,6 +17,42 @@ og:description: See what's new in the latest release of Roseau Load Flow !
 
 # Changelog
 
+## Version 0.12.0-alpha
+
+- 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.
+
 ## Version 0.11.0
 
 This release adds official support for Python 3.13 and adds a new experimental backward-forward solver.

doc/Installation.md

@@ -114,7 +114,7 @@ the corresponding functions. They can be installed with the
 If you are using Jupyter Notebooks, you can install `roseau-load-flow` directly from a notebook
 cell with:
 
-```python-console
+```ipython
 In [1]: %pip install roseau-load-flow
 ```
 

doc/License.md

@@ -124,7 +124,7 @@ variable:
    ROSEAU_LOAD_FLOW_LICENSE_KEY="A8C6DA-9405FB-E74FB9-C71C3C-207661-V3"
    ```
 2. Add a cell to the beginning of your notebook with the following content and execute it:
-   ```python-console
+   ```ipython
    %pip install python-dotenv
    %load_ext dotenv
    %dotenv

doc/conf.py

@@ -4,6 +4,8 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+
 # -- Path setup --------------------------------------------------------------
 
 
@@ -22,8 +24,8 @@
 # author = "Benoît Vinot"
 
 # The full version, including alpha/beta/rc tags
-version = "0.11"
-release = "0.11.0"
+version = "0.12"
+release = "0.12.0-alpha"
 
 # -- General configuration ---------------------------------------------------
 
@@ -41,7 +43,6 @@
     "sphinx_inline_tabs",
     "sphinxcontrib.googleanalytics",
     "sphinxcontrib.bibtex",
-    "sphinx_sitemap",
     "sphinxext.opengraph",
 ]
 myst_enable_extensions = ["deflist", "smartquotes", "replacements", "dollarmath"]
@@ -105,6 +106,9 @@
     ],
 }
 
+# See https://docs.readthedocs.io/en/stable/canonical-urls.html
+html_baseurl = os.getenv("READTHEDOCS_CANONICAL_URL", "https://roseau-load-flow.roseautechnologies.com/page/")
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -132,7 +136,16 @@
 
 # -- Options for AutoAPI -------------------------------------------------
 autoapi_dirs = ["../roseau"]
-autoapi_ignore = ["**/tests/**", "**/conftest.py", "__about__.py"]
+autoapi_ignore = [
+    # Tests
+    "**/tests/**",
+    "**/conftest.py",
+    # Cruft
+    "**/roseau/load_flow/__about__.py",
+    # Internal utilities
+    "**/roseau/load_flow/utils/**",
+    "**/roseau/load_flow/io/**",
+]
 autoapi_options = ["members", "show-inheritance", "show-module-summary", "imported-members"]
 autoapi_python_class_content = "both"  # without this, the __init__ docstring is not shown
 autoapi_python_use_implicit_namespaces = True
@@ -173,11 +186,6 @@
     "gh-pr": ("https://github.com/RoseauTechnologies/Roseau_Load_Flow/pull/%s", "PR%s"),
 }
 
-
-# -- Options for sphinx-sitemap -----------------------------------------
-html_baseurl = "https://roseau-load-flow.roseautechnologies.com/"
-sitemap_url_scheme = "{link}"  # default is {lang}{version}{link}
-
 # -- Options for sphinx-opengraph -----------------------------------------
-ogp_site_url = "https://roseau-load-flow.roseautechnologies.com/"
-ogp_image = "https://roseau-load-flow.roseautechnologies.com/_static/Roseau_Load_Flow_Stacked.svg"
+ogp_site_url = "https://roseau-load-flow.roseautechnologies.com/page/"
+ogp_image = "https://roseau-load-flow.roseautechnologies.com/page/_static/Roseau_Load_Flow_Stacked.svg"

doc/index.md

@@ -15,32 +15,15 @@ myst:
 
 # Welcome to the Roseau Load Flow documentation
 
-_Roseau Load Flow_ is a powerful multi-phase load flow solver for unbalanced power flow analysis that
-offers:
-
-- Multi-phase, unbalanced power flow analysis
-- Performance optimized solver written in C++
-- A catalogue of real-world transformer and line models
-- An ergonomic object-oriented Python interface
-- A comprehensive documentation with code examples
-- Real-world distribution network data samples in the library (with more available on request)
-
-In addition to the following _unique_ set of features:
-
-- Support for floating neutrals for loads and sources
-- Four-wire multi-phase modelling with no Kron's reduction, no transformations, no assumptions on the
-  network topology and no implicit earthing everywhere
-- Support for flexible, voltage-dependent, loads directly in the Newton algorithm for better convergence
-
-This software is developed by [Roseau Technologies](https://www.roseautechnologies.com/en).
-<a href="https://www.linkedin.com/company/roseau-technologies/"><i class="fa-brands fa-linkedin" ></i></a>
-<a href="https://github.com/RoseauTechnologies/"><i class="fa-brands fa-github" ></i></a>
-
-_Roseau Load Flow_ ships with a sample of 20 low-voltage and 20 medium-voltage feeder networks. Each
-network is provided with its summer and winter load points. At _Roseau Technologies_, we can provide
-the major part of the French medium and low voltage networks on demand. For more information, please
-contact us at
-[contact@roseautechnologies.com](mailto:contact@roseautechnologies.com).
+```{include} ../README.md
+:start-after: <!-- start rlf-pitch -->
+:end-before: <!-- end rlf-pitch -->
+```
+
+```{include} ../README.md
+:start-after: <!-- start rlf-networks -->
+:end-before: <!-- end rlf-networks -->
+```
 
 <iframe src="./_static/Network/Catalogue.html" height="600px" width="100%" frameborder="0"></iframe>
 

doc/models/Bus.md

@@ -80,7 +80,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_((0.3 + 0.35j) * np.eye(4), "ohm/k
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The neutral of bus1 is fixed at potential 0

doc/models/Line/ShuntLine.md

@@ -121,7 +121,7 @@ line = rlf.Line(
 )
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 

doc/models/Line/SimplifiedLine.md

@@ -66,7 +66,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V

doc/models/Load/CurrentLoad.md

@@ -64,7 +64,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V

doc/models/Load/FlexibleLoad/FeasibleDomain.md

@@ -42,7 +42,7 @@ import roseau.load_flow as rlf
 
 # A voltage source
 bus = rlf.Bus(id="bus", phases="abcn")
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus, voltages=rlf.Q_(un, "V"))
 
 # A potential ref

doc/models/Load/ImpedanceLoad.md

@@ -61,7 +61,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V

doc/models/Load/PowerLoad.md

@@ -64,7 +64,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V

doc/models/Switch.md

@@ -52,7 +52,7 @@ bus2 = rlf.Bus(id="bus2", phases="abcn")
 switch = rlf.Switch(id="switch", bus1=bus1, bus2=bus2)
 
 # A voltage source on the first bus
-vs = rlf.VoltageSource(id="source", bus=bus1, voltages=400 / np.sqrt(3))
+vs = rlf.VoltageSource(id="source", bus=bus1, voltages=400 / rlf.SQRT3)
 
 # The potential of the neutral of bus1 is fixed at 0V
 pref = rlf.PotentialRef(id="pref", element=bus1)

doc/models/Transformer/Single_Phase_Transformer.md

@@ -75,7 +75,7 @@ import roseau.load_flow as rlf
 bus1 = rlf.Bus(id="bus1", phases="abcn")
 pref1 = rlf.PotentialRef(id="pref1", element=bus1)
 
-vs = rlf.VoltageSource(id="vs", bus=bus1, voltages=400 / np.sqrt(3))
+vs = rlf.VoltageSource(id="vs", bus=bus1, voltages=400 / rlf.SQRT3)
 
 # Create the load bus and the load
 bus2 = rlf.Bus(id="bus2", phases="an")

doc/usage/Connecting_Elements.md

@@ -31,7 +31,7 @@ Let's take the electrical network of the [Getting started page](usage-getting-st
 ... pref = rlf.PotentialRef(id="pref", element=ground)
 ... ground.connect(source_bus, phase="n")
 
->>> un = 400 / np.sqrt(3)
+>>> un = 400 / rlf.SQRT3
 ... vs = rlf.VoltageSource(id="vs", bus=source_bus, voltages=un)
 
 >>> load = rlf.PowerLoad(id="load", bus=load_bus, powers=[10e3 + 0j, 10e3, 10e3])  # VA