Merge pull request #265 from RoseauTechnologies/develop

Version 0.10.0

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
     hooks:
       - id: poetry-check
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.0
+    rev: v0.6.3
     hooks:
       - id: ruff
         types_or: [python, pyi, jupyter]
@@ -29,13 +29,13 @@ repos:
         files: ^doc/.*\.md$
         args: [-l 90]
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.3.2
+    rev: v3.3.3
     hooks:
       - id: prettier
         args: ["--print-width", "120"]
         require_serial: true
   - repo: https://github.com/cmhughes/latexindent.pl
-    rev: V3.24.2
+    rev: V3.24.4
     hooks:
       - id: latexindent
         args: [-l, -m, -s, -wd]

.vscode/cspell.json

@@ -27,6 +27,8 @@
     "elmlodmv",
     "elmpvsys",
     "furo",
+    "gpslat",
+    "gpslon",
     "gscale",
     "htmlcov",
     "ilini",
@@ -49,6 +51,7 @@
     "pcutr",
     "pgini",
     "phasor",
+    "phasors",
     "phtech",
     "pipx",
     "plini",

doc/Changelog.md

@@ -17,6 +17,76 @@ og:description: See what's new in the latest release of Roseau Load Flow !
 
 # Changelog
 
+## Version 0.10.0
+
+- A wheel for Python 3.13 is also 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`.
+
 ## Version 0.9.1
 
 ```{note}
@@ -135,7 +205,7 @@ Starting with version 0.7.0, Roseau Load Flow is no longer supplied as a SaaS. T
 a standalone Python library.
 ```
 
-- The documentation is moved from GitHub Pages to <https://www.roseau-load-flow.roseautechnologies.com/>.
+- The documentation is moved from GitHub Pages to <https://roseau-load-flow.roseautechnologies.com/>.
 - Fix a bug in the engine: it was impossible to change the parameters of center-tapped and single phase transformers.
 - {gh-pr}`179` Fix a bug in the propagation of potentials when a center-tapped transformer is used without neutral at
   the primary side.

doc/License.md

@@ -2,74 +2,91 @@
 myst:
   html_meta:
     "description lang=en": |
-      Depending on your status, Roseau Load Flow is available with several types of free or paid licences. A trial
+      Depending on your status, Roseau Load Flow is available with several types of free or paid licenses. A trial
        key is also available.
     "description lang=fr": |
       En fonction de votre statut, Roseau Load Flow est disponible avec plusieurs types de licences gratuites ou
        payantes. Une clef d'essai est également disponible.
     "keywords lang=fr": solveur, simulation, réseau, électrique, licence, open-source, gratuit, essai
-    "keywords lang=en": simulation, distribution grid, solver, open-source, free, test
+    "keywords lang=en": simulation, distribution grid, solver, license, open-source, free, test
 og:image: https://www.roseautechnologies.com/wp-content/uploads/2024/04/DSCF0265-scaled.webp
 og:image:alt: An engineer uses Roseau Load Flow to perform compute the electric state of a MV/LV transformer
-og:title: Free public licence key
+og:title: Free public license key
 og:description: |
-  You can try out RLF without registration on a distribution network of up to ten nodes by using the public licence
+  You can try out RLF without registration on a distribution network of up to ten nodes by using the public license
   key provided below.
 ---
 
 (license-page)=
 
-# Get and activate your licence
+# Get and activate your license
+
+This project is partially open source. The source code of the Python interface is available on
+[GitHub](https://github.com/RoseauTechnologies/Roseau_Load_Flow) under the
+[BSD 3-Clause License](https://github.com/RoseauTechnologies/Roseau_Load_Flow/blob/main/LICENSE.md).
+The solver used in this project is not open source. You need a valid license key to use it.
 
 (license-types)=
 
-## Commercial and free licences
+## Types of licenses
 
-This project is partially open source. The source code of this repository is available under the
-[BSD 3-Clause License](https://github.com/RoseauTechnologies/Roseau_Load_Flow/blob/main/LICENSE.md).
+### Trial license (free)
 
-The solver used in this project is not open source. A license has to be purchased to use it. To
-obtain a personal or commercial license, please contact us at
-[contact@roseautechnologies.com](mailto:contact@roseautechnologies.com).
+The license key **`A8C6DA-9405FB-E74FB9-C71C3C-207661-V3`** can be used with networks containing up
+to 10 buses. For example, this key can be used to follow the tutorials in this documentation or for
+personal projects. This key is valid indefinitely.
 
-For networks with less than 11 buses (up to 10 buses), the license key `A8C6DA-9405FB-E74FB9-C71C3C-207661-V3`
-can be used free of charge. For example, this key can be used to follow the getting started guide.
+### Academic license (free)
 
-```{note}
-Licenses are given **free of charge** for _students and teachers_. Please contact us at
-[contact@roseautechnologies.com](mailto:contact@roseautechnologies.com) to get a license key.
-```
+_Students and teachers_ are eligible for **free unlimited licenses** to use in academic projects.
+Please reach out to us at [contact@roseautechnologies.com](mailto:contact@roseautechnologies.com) to
+obtain your free license key. The license key will be valid for one year and can be renewed.
+
+### Commercial license (paid)
+
+For other commercial or personal use, a license has to be purchased. Please contact us at
+[contact@roseautechnologies.com](mailto:contact@roseautechnologies.com) to obtain a personalized
+license.
 
 (license-activation)=
 
 ## How to activate the license in your project?
 
 There are two ways to activate the license in your project:
 
-1. Set the environment variable `ROSEAU_LOAD_FLOW_LICENSE_KEY` to the license key. When this
-   environment variable is defined, it will automatically be used by the solver to validate the
-   license, no further action is required.
-   **This is the recommended approach.**
-   ```{note}
-   If you need help setting an environment variable, refer to the section
-   [How to set an environment variable?](license-environment-variable)
-   ```
-2. Call the function `activate_license` with the license key as argument. This function will
-   activate the license for the current session. If you use this approach, it is recommended to
-   store the license key in a file and read it from there to avoid hard coding it in your code and
-   accidentally committing it to your repository. Example:
+### Via environment variables (recommended)
 
-   ```python
-   from pathlib import Path
-   import roseau.load_flow as rlf
+Set the environment variable `ROSEAU_LOAD_FLOW_LICENSE_KEY` to the license key. When this environment
+variable is defined, it will automatically be used by the solver to validate the license, no further
+action is required.
 
-   rlf.activate_license(Path("my_license_key.txt").read_text().strip())
+Please refer to the [How to set an environment variable?](license-environment-variable) section below
+if you need help setting an environment variable.
 
-   # Rest of your code here
-   ```
+### Using the `activate_license` function
 
-   where the file `my_license_key.txt` contains `A8C6DA-9405FB-E74FB9-C71C3C-207661-V3` (replace
-   with your license key).
+Call the function `activate_license` with the license key as argument. This function will activate
+the license for the current session. If you use this approach, it is recommended to store the
+license key in a file and read it from there to avoid hard coding it in your code and accidentally
+committing it to your repository. Example:
+
+```python
+from pathlib import Path
+import roseau.load_flow as rlf
+
+rlf.activate_license(Path("my_license_key.txt").read_text().strip())
+
+# Rest of your code here
+```
+
+where the file `my_license_key.txt` contains `A8C6DA-9405FB-E74FB9-C71C3C-207661-V3` (replace
+with your license key).
+
+```{important}
+Do not share your license key with others. The license key is personal and should not be shared
+publicly. If you use a version control system like _Git_, make sure to exclude the file containing
+the license key from versioning by adding it to your `.gitignore` file.
+```
 
 (license-environment-variable)=