Merge pull request #294 from RoseauTechnologies/develop

Version 0.11.0

.github/workflows/ci.yml

@@ -16,14 +16,15 @@ on:
 
 env:
   CI: true
+  UV_SYSTEM_PYTHON: 1
 
 jobs:
   build:
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4
@@ -49,24 +50,23 @@ jobs:
           git lfs pull
           git lfs prune --verify-remote
 
-      - name: Install poetry
-        run: pipx install poetry
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: "poetry"
 
       - name: Install dependencies
         run: |
-          poetry env use "${{ matrix.python-version }}"
-          poetry install --without dev
+          uv sync --frozen --all-extras
 
       - name: Test with pytest
         run: |
-          poetry run pytest -vv -n=auto --durations=25 --cov-report html \
-          --cov-config pyproject.toml roseau
+          uv run pytest -vv -n=auto --durations=25 --cov-report html --cov-config pyproject.toml roseau
         env:
           ROSEAU_LOAD_FLOW_LICENSE_KEY: ${{ secrets.ROSEAU_LOAD_FLOW_LICENSE_KEY }}
 

.github/workflows/pre-commit.yml

@@ -23,5 +23,5 @@ jobs:
           lfs: false
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
       - uses: pre-commit/[email protected]

.latexindent.yaml

@@ -39,6 +39,7 @@ indentRules:
 modifyLineBreaks:
   textWrapOptions:
     columns: 120
+    when: after
   environments:
     BeginStartsOnOwnLine: 1
     BodyStartsOnOwnLine: 1

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 exclude: ^.idea/|.vscode/
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-json
       - id: check-merge-conflict
@@ -10,26 +10,24 @@ repos:
       - id: detect-private-key
       - id: end-of-file-fixer
       - id: trailing-whitespace
-  - repo: https://github.com/python-poetry/poetry
-    rev: 1.8.0
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.5.5
     hooks:
-      - id: poetry-check
+      - id: uv-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.3
+    rev: v0.8.1
     hooks:
       - id: ruff
-        types_or: [python, pyi, jupyter]
         args: [--fix]
       - id: ruff-format
-        types_or: [python, pyi, jupyter]
   - repo: https://github.com/adamchainz/blacken-docs
-    rev: 1.18.0
+    rev: 1.19.1
     hooks:
       - id: blacken-docs
         files: ^doc/.*\.md$
         args: [-l 90]
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.3.3
+    rev: v3.4.1
     hooks:
       - id: prettier
         args: ["--print-width", "120"]

.readthedocs.yaml

@@ -0,0 +1,33 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  commands:
+    #
+    # Install git-lfs
+    #
+    # Download and uncompress the binary
+    # https://git-lfs.github.com/
+    - wget https://github.com/git-lfs/git-lfs/releases/download/v3.6.0/git-lfs-linux-amd64-v3.6.0.tar.gz
+    - tar xvfz git-lfs-linux-amd64-v3.6.0.tar.gz
+    # Modify LFS config paths to point where git-lfs binary was downloaded
+    - git config filter.lfs.process "`pwd`/git-lfs filter-process"
+    - git config filter.lfs.smudge  "`pwd`/git-lfs smudge -- %f"
+    - git config filter.lfs.clean "`pwd`/git-lfs clean -- %f"
+    # Make LFS available in current repository
+    - ./git-lfs-3.6.0/git-lfs install
+    # Download content from remote
+    - ./git-lfs-3.6.0/git-lfs fetch
+    # Make local files to have the real content on them
+    - ./git-lfs-3.6.0/git-lfs checkout
+    #
+    # Build using uv
+    #
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --only-group doc --frozen
+    - uv run -m sphinx -T -b html -d doc/_build/doctrees doc $READTHEDOCS_OUTPUT/html

README.md

@@ -2,23 +2,35 @@
 
 ![CI](https://github.com/RoseauTechnologies/Roseau_Load_Flow/workflows/CI/badge.svg)
 ![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 highly capable three-phase load flow solver with an ergonomic Python API
-for unbalanced power flow analysis.
+_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 project is compatible with Python version 3.10 and newer. The
 [installation instructions](https://roseau-load-flow.roseautechnologies.com/Installation.html)
-will guide you through the installation process. If you are new to _Roseau Load Flow_, we recommend you start with the
+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).
 You can find the complete documentation at https://roseau-load-flow.roseautechnologies.com/.
 
-> [!IMPORTANT]
-> Starting with version 0.7.0, Roseau Load Flow is no longer supplied as a SaaS. The software is now
-> available as a standalone Python library.
-
 ## License
 
-The project is _partially_ open source but using the solver requires a license. The license key
+This project is _partially_ open source but using the solver requires a license. The license key
 `A8C6DA-9405FB-E74FB9-C71C3C-207661-V3` can be used free of charge with networks containing up to 10
 buses. To obtain a personal or commercial license, please contact us
 at [[email protected]](mailto:[email protected]).
@@ -31,21 +43,25 @@ Read more at [License](https://roseau-load-flow.roseautechnologies.com/License.h
 
 ## Network data
 
-With this library, there is a sample of 20 low-voltage and 20 medium-voltage feeders included for an easy
-start! Each network is given with its summer and winter load point. At _Roseau Technologies_, we are able to provide
-the major part of the French medium and low voltage networks. For more information, please contact us at
-[email protected].
+_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.
 
-![Catalogue of networks](https://github.com/RoseauTechnologies/Roseau_Load_Flow/blob/main/doc/_static/Network/Catalogue.png?raw=True)
+<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>
 
 ## Bug reports / Feature requests
 
-If you find a bug or have a feature request, please open an issue on
+For bug reports, feature requests, or questions, please open an issue on
 [GitHub](https://github.com/RoseauTechnologies/Roseau_Load_Flow/issues)
 
 ## Credits
 
 This software is developed by [Roseau Technologies](https://www.roseautechnologies.com/en).
-[![Linkedin](https://i.stack.imgur.com/gVE0j.png) LinkedIn](https://www.linkedin.com/company/roseau-technologies/)
+
+Follow us on:
+[![Linkedin](https://i.sstatic.net/gVE0j.png) LinkedIn](https://www.linkedin.com/company/roseau-technologies/)
 &nbsp;
-[![GitHub](https://i.stack.imgur.com/tskMh.png) GitHub](https://github.com/RoseauTechnologies)
+[![GitHub](https://i.sstatic.net/tskMh.png) GitHub](https://github.com/RoseauTechnologies)

doc/Changelog.md

@@ -17,9 +17,106 @@ og:description: See what's new in the latest release of Roseau Load Flow !
 
 # Changelog
 
+## 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
+
+- {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.
+
 ## Version 0.10.0
 
-- A wheel for Python 3.13 is also available.
+- 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.

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:
 
-```ipython3
+```python-console
 In [1]: %pip install roseau-load-flow
 ```
 

doc/License.md

@@ -93,10 +93,26 @@ the license key from versioning by adding it to your `.gitignore` file.
 ## How to set an environment variable?
 
 If you are not sure how to set an environment variable, [this article](https://www.bitecode.dev/p/environment-variables-for-beginners)
-has instructions for Windows, MacOS and Linux. The section [Persisting an environment variable](https://www.bitecode.dev/i/121864947/persisting-an-environment-variable)
+has instructions for Windows, macOS and Linux. The section [Persisting an environment variable](https://www.bitecode.dev/i/121864947/persisting-an-environment-variable)
 explains how to make the environment variable persistent on your machine so that you don't have to
 set it every time you open a new terminal.
 
+### For Google Colab users
+
+The "Secrets" feature in Google Colab is very useful for defining local variables. In the left panel, open the 'Secrets' section. Create a new variable called `ROSEAU_LOAD_FLOW_LICENSE_KEY`, with the value being your license key. This variable is personal to you, and the toggle will allow you to enable access to the license key for notebooks of your choice.
+
+```{image} /_static/2024_09_16_Google_Colab_Environment_Variable.png
+:alt: Google Colab environment variable
+:align: center
+```
+
+To set the environment variable, add the following in a cell at the beginning of your notebook:
+
+```
+from google.colab import userdata
+os.environ['ROSEAU_LOAD_FLOW_LICENSE_KEY'] = userdata.get('ROSEAU_LOAD_FLOW_LICENSE_KEY')
+```
+
 ### For Jupyter Notebook users
 
 If you are using a _Jupyter Notebook_, you can follow these instructions to set the environment
@@ -108,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:
-   ```ipython3
+   ```python-console
    %pip install python-dotenv
    %load_ext dotenv
    %dotenv