Merge pull request #141 from RoseauTechnologies/networkx

Add support for Python 3.12 and networkx graphs

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4

.github/workflows/doc.yml

@@ -57,20 +57,20 @@ jobs:
       - name: Install poetry
         run: pipx install poetry
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           cache: "poetry"
 
       - name: Install dependencies
         run: |
-          poetry env use "3.11"
+          poetry env use "3.12"
           poetry install --only doc
 
       - name: Build with Sphinx
         run: |
-          poetry env use "3.11"
+          poetry env use "3.12"
           cd doc && make html
         env:
           SPHINXBUILD: poetry run sphinx-build

.github/workflows/pre-commit.yml

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

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 exclude: ^.idea/|^conda/meta.yaml
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: check-builtin-literals
       - id: check-json
@@ -17,11 +17,11 @@ repos:
     hooks:
       - id: poetry-check
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.9.1 # keep in sync with pyproject.toml
+    rev: 23.10.1 # keep in sync with pyproject.toml
     hooks:
       - id: black-jupyter
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.290 # keep in sync with pyproject.toml
+    rev: v0.1.3 # keep in sync with pyproject.toml
     hooks:
       - id: ruff
         types_or: [python, pyi, jupyter]

conda/environment.yml

@@ -14,3 +14,4 @@ dependencies:
   - typing-extensions >=4.6.2
   - rich >=13.5.1
   - matplotlib >=3.7.2
+  - networkx >=3.0.0

conda/meta.yaml

@@ -36,6 +36,7 @@ requirements:
     - typing-extensions >=4.6.2
     - rich >=13.5.1
     - matplotlib >=3.7.2
+    - networkx >=3.0.0
 
 test:
   imports:

doc/Changelog.md

@@ -4,6 +4,14 @@
 
 **In development**
 
+- {gh-pr}`141` {gh-issue}`137` Add `ElectricalNetwork.to_graph()` to get a `networkx.Graph` object
+  representing the electrical network for graph theory studies. Install with the `"graph"` extra to
+  get _networkx_.
+  `ElectricalNetwork` also gained a new `buses_clusters` property that returns a list of sets of
+  IDs of buses that are connected by a line or a switch. This can be useful to isolate parts of the
+  network for localized analysis. For example, to study a LV subnetwork of a MV feeder. Alternatively,
+  to get the cluster certain bus belongs to, you can use `Bus.get_connected_buses()`.
+- {gh-pr}`141` Add official support for Python 3.12. This is the last release to support Python 3.9.
 - {gh-pr}`138` Add network constraints for analysis of the results.
   - Buses can define minimum and maximum voltages. Use `bus.res_violated` to see if the bus has
     over- or under-voltage.

doc/conf.py

@@ -130,6 +130,8 @@
     "pint": ("https://pint.readthedocs.io/en/stable/", None),
     "typing_extensions": ("https://typing-extensions.readthedocs.io/en/stable/", None),
     "rich": ("https://rich.readthedocs.io/en/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "networkx": ("https://networkx.org/documentation/stable/", None),
 }
 
 # -- Options for sphinx_copybutton -------------------------------------------

doc/usage/Extras.md

@@ -2,6 +2,40 @@
 
 `roseau-load-flow` comes with some extra features that can be useful for some users.
 
+## Graph theory
+
+{meth}`ElectricalNetwork.to_graph() <roseau.load_flow.ElectricalNetwork.to_graph>` can be used to
+get a {class}`networkx.Graph` object from the electrical network.
+
+The graph contains the geometries of the buses in the nodes data and the geometries and branch
+types in the edges data.
+
+```{note}
+This method requires *networkx* which is not installed by default in pip managed installs. You can
+install it with the `"graph"` extra if you are using pip: `pip install "roseau-load-flow[graph]"`.
+```
+
+In addition, you can use the property
+{meth}`ElectricalNetwork.buses_clusters <roseau.load_flow.ElectricalNetwork.buses_clusters>` to
+get a list of sets of IDs of buses in galvanically isolated sections of the network. In other terms,
+to get groups of buses connected by one or more lines or a switches, stopping at transformers. For
+example, for a network with a MV feeder, this property returns a list containing a set of MV buses
+IDs and all sets of LV subnetworks buses IDs. If you want to get the cluster of only one bus, you
+can use {meth}`Bus.get_connected_buses <roseau.load_flow.models.Bus.get_connected_buses>`
+
+If we take the example network from the [Getting Started page](gs-creating-network):
+
+```pycon
+>>> set(source_bus.get_connected_buses())
+{'sb', 'lb'}
+>>> set(load_bus.get_connected_buses())
+{'sb', 'lb'}
+>>> en.buses_clusters
+[{'sb', 'lb'}]
+```
+
+As there are no transformers between the two buses, they all belong to the same cluster.
+
 ## Conversion to symmetrical components
 
 {mod}`roseau.load_flow.converters` contains helpers to convert between phasor and symmetrical

doc/usage/Getting_Started.md

@@ -492,8 +492,7 @@ the limits are violated or not for the corresponding element.
 
 ```{tip}
 You can use the {meth}`Bus.propagate_limits() <roseau.load_flow.Bus.propagate_limits>` method to
-propagate the limits from a bus to its neighboring buses, that is, buses on the same side of a
-transformer.
+propagate the limits from a bus to buses connected to it galvanically (i.e. via lines or switches).
 ```
 
 (gs-updating-elements)=