Merge branch main into feature/Cleanup-import-statements2 and resolve conflicts

Signed-off-by: Emanuele Brentegani <emabr90@gmail.com>

Author: emabre

.github/workflows/build-test-release.yml

@@ -13,11 +13,6 @@ on:
         type: boolean
         description: Create a (pre-)release when CI passes
         required: true
-    secrets:
-      PYPI_USER:
-        required: true
-      PYPI_PASS:
-        required: true
   # run this workflow manually from the Actions tab
   workflow_dispatch:
     inputs:
@@ -44,12 +39,13 @@ jobs:
           python-version: "3.12"
 
       - name: Set PyPI Version
-        run: |
-          pip install requests build
-          python set_pypi_version.py
+        uses: PowerGridModel/pgm-version-bump@main
 
       - name: Build SDist
-        run: python -m build --sdist --outdir wheelhouse .
+        run: |
+          cat PYPI_VERSION
+          pip install build
+          python -m build --sdist --outdir wheelhouse .
 
       - name: Keep version file
         uses: actions/upload-artifact@v4
@@ -283,16 +279,14 @@ jobs:
       - name: Test
         run: pytest
 
-  publish-wheels:
+  github-release:
+    name: Create and release assets to GitHub
     needs: [build-cpp-test-linux, build-cpp-test-windows, build-cpp-test-macos, build-and-test-python, build-and-test-conda]
     # always run publish job but fail at the first step if previous jobs have been failed
     if: always()
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     permissions:
       contents: write
-    env:
-      TWINE_USERNAME: ${{ secrets.PYPI_USER }}
-      TWINE_PASSWORD: ${{ secrets.PYPI_PASS }}
 
     steps:
       - name: Fail fast
@@ -329,14 +323,7 @@ jobs:
       - name: Display tag
         run: echo "${{ steps.tag.outputs.tag }}"
 
-      - name: Upload wheels
-        if: (inputs.create_release)
-        run: |
-          pip install twine
-          echo "Publish to PyPI..."
-          twine upload --verbose wheelhouse/*
-
-      - name: Release
+      - name: Create GitHub release
         uses: softprops/action-gh-release@v2
         if: (inputs.create_release)
         with:

.github/workflows/check-code-quality.yml

@@ -61,6 +61,12 @@ jobs:
           sudo apt-get update && sudo apt-get install -y clang-format-18
           find . -regex '.*\.\(h\|c\|cpp\|hpp\|cc\|cxx\)' -exec clang-format-18 -style=file -i {} \;
 
+      - name: Install and run markdownlint
+        run: |
+          npm install -g markdownlint-cli
+          echo "Running markdownlint"
+          markdownlint --fix .
+
       - name: If needed raise error
         run: |
 

.github/workflows/ci.yml

@@ -43,9 +43,6 @@ jobs:
       # create_release becomes true if the event that triggered this workflow is "push" on main
       # otherwise create_release becomes false
       create_release: ${{ (github.event_name == 'workflow_dispatch' && inputs.create_release) || github.event_name == 'push'}}
-    secrets:
-      PYPI_USER: ${{ secrets.PYPI_USER }}
-      PYPI_PASS: ${{ secrets.PYPI_PASS }}
 
   check-code-quality:
     uses: "./.github/workflows/check-code-quality.yml"

.github/workflows/nightly.yml

@@ -21,9 +21,6 @@ jobs:
       contents: write
     with:
       create_release: false
-    secrets:
-      PYPI_USER: user
-      PYPI_PASS: pass
 
   check-code-quality:
     uses: "./.github/workflows/check-code-quality.yml"

.github/workflows/publish-pypi.yml

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write  # Required for Trusted Publishing
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download assets from GitHub release
+        uses: robinraju/release-downloader@v1
+        with:
+          repository: ${{ github.repository }}
+          # download the latest release
+          latest: true
+          # don't donwload pre-releases
+          preRelease: false
+          fileName: "*"
+          # don't download GitHub-generated source tar and zip files
+          tarBall: false
+          zipBall: false
+          # create a directory to store the downloaded assets
+          out-file-path: assets-to-publish
+          # don't extract downloaded files
+          extract: false
+
+      - name: List downloaded assets
+        run: ls -la assets-to-publish
+      
+      - name: Upload assets to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # To test, use the TestPyPI:
+          # repository-url: https://test.pypi.org/legacy/
+          # You must also create an account and project on TestPyPI,
+          # as well as set the trusted-publisher in the project settings:
+          # https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+          # To publish to the official PyPI repository, just keep
+          # repository-url commented out.
+          packages-dir: assets-to-publish
+          skip-existing: true
+          print-hash: true
+          verbose: true

.markdownlint.yaml

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md001.md
+MD001: false
+
+# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md
+MD013: false
+  # # Number of characters
+  # line_length: 80
+  # # Number of characters for headings
+  # heading_line_length: 80
+  # # Number of characters for code blocks
+  # code_block_line_length: 80
+  # # Include code blocks
+  # code_blocks: true
+  # # Include tables
+  # tables: true
+  # # Include headings
+  # headings: true
+  # # Strict length checking
+  # strict: false
+  # # Stern length checking
+  # stern: false
+
+# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md024.md
+MD024: false

.pre-commit-config.yaml

@@ -41,3 +41,8 @@ repos:
     hooks:
       - id: clang-format
         types_or: [ c++, c ]
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.44.0
+    hooks:
+    - id: markdownlint
+      args: ["--fix"]

.vscode/extensions.json

@@ -24,6 +24,7 @@
 		"matepek.vscode-catch2-test-adapter",
 		"cschlosser.doxdocgen",
 		"fredericbonnet.cmake-test-adapter",
-		"sonarsource.sonarlint-vscode"
+		"sonarsource.sonarlint-vscode",
+		"davidanson.vscode-markdownlint"
 	]
 }

README.md

@@ -4,16 +4,13 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridm
 SPDX-License-Identifier: MPL-2.0
 -->
 
-[![PyPI version](https://badge.fury.io/py/power-grid-model.svg?no-cache)](https://badge.fury.io/py/power-grid-model)
+[![PyPI version](https://badge.fury.io/py/power-grid-model.svg?no-cache)](https://badge.fury.io/py/power-grid-model) <!-- markdownlint-disable-line first-line-h1 -->
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/power-grid-model/badges/version.svg?no-cache)](https://anaconda.org/conda-forge/power-grid-model)
 [![License: MPL2.0](https://img.shields.io/badge/License-MPL2.0-informational.svg)](https://github.com/PowerGridModel/power-grid-model/blob/main/LICENSE)
 [![Downloads](https://static.pepy.tech/badge/power-grid-model)](https://pepy.tech/project/power-grid-model)
 [![Downloads](https://static.pepy.tech/badge/power-grid-model/month)](https://pepy.tech/project/power-grid-model)
 
-[![Build and Test C++ and Python](https://github.com/PowerGridModel/power-grid-model/actions/workflows/ci.yml/badge.svg)](https://github.com/PowerGridModel/power-grid-model/actions/workflows/build-test-release.yml)
-[![Check Code Quality](https://github.com/PowerGridModel/power-grid-model/actions/workflows/ci.yml/badge.svg)](https://github.com/PowerGridModel/power-grid-model/actions/workflows/check-code-quality.yml)
-[![Clang Tidy](https://github.com/PowerGridModel/power-grid-model/actions/workflows/ci.yml/badge.svg)](https://github.com/PowerGridModel/power-grid-model/actions/workflows/clang-tidy.yml)
-[![REUSE Compliance Check](https://github.com/PowerGridModel/power-grid-model/actions/workflows/ci.yml/badge.svg)](https://github.com/PowerGridModel/power-grid-model/actions/workflows/reuse-compliance.yml)
+[![CI Build](https://github.com/PowerGridModel/power-grid-model/actions/workflows/ci.yml/badge.svg)](https://github.com/PowerGridModel/power-grid-model/actions/workflows/ci.yml)
 [![docs](https://readthedocs.org/projects/power-grid-model/badge/)](https://power-grid-model.readthedocs.io/en/stable/)
 
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=PowerGridModel_power-grid-model&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=PowerGridModel_power-grid-model)
@@ -27,7 +24,7 @@ SPDX-License-Identifier: MPL-2.0
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8054429.svg)](https://zenodo.org/record/8054429)
 
-[![](https://github.com/PowerGridModel/.github/blob/main/artwork/svg/color.svg)](#)
+[![Power Grid Model logo](https://github.com/PowerGridModel/.github/blob/main/artwork/svg/color.svg)](#) <!-- markdownlint-disable-line no-empty-links -->
 
 # Power Grid Model
 
@@ -53,15 +50,15 @@ Want to be updated on the latest news and releases? Subscribe to the Power Grid
 
 You can directly install the package from PyPI.
 
-```
+```sh
 pip install power-grid-model
 ```
 
 ### Install from Conda
 
 If you are using `conda`, you can directly install the package from `conda-forge` channel.
 
-```
+```sh
 conda install -c conda-forge power-grid-model
 ```
 
@@ -71,7 +68,7 @@ To install the library from source, refer to the [Build Guide](https://power-gri
 
 ## Examples
 
-Please refer to [Examples](https://github.com/PowerGridModel/power-grid-model-workshop/tree/main/examples) for more detailed examples for power flow and state estimation. 
+Please refer to [Examples](https://github.com/PowerGridModel/power-grid-model-workshop/tree/main/examples) for more detailed examples for power flow and state estimation.
 Notebooks for validating the input data and exporting input/output data are also included.
 
 ## License
@@ -80,14 +77,14 @@ This project is licensed under the Mozilla Public License, version 2.0 - see [LI
 
 ## Licenses third-party libraries
 
-This project includes third-party libraries, 
+This project includes third-party libraries,
 which are licensed under their own respective Open-Source licenses.
-SPDX-License-Identifier headers are used to show which license is applicable. 
+SPDX-License-Identifier headers are used to show which license is applicable.
 The concerning license files can be found in the [LICENSES](https://github.com/PowerGridModel/power-grid-model/tree/main/LICENSES) directory.
 
 ## Contributing
 
-Please read [CODE_OF_CONDUCT](https://github.com/PowerGridModel/.github/blob/main/CODE_OF_CONDUCT.md), [CONTRIBUTING](https://github.com/PowerGridModel/.github/blob/main/CONTRIBUTING.md), [PROJECT GOVERNANCE](https://github.com/PowerGridModel/.github/blob/main/GOVERNANCE.md) and [RELEASE](https://github.com/PowerGridModel/.github/blob/main/RELEASE.md) for details on the process 
+Please read [CODE_OF_CONDUCT](https://github.com/PowerGridModel/.github/blob/main/CODE_OF_CONDUCT.md), [CONTRIBUTING](https://github.com/PowerGridModel/.github/blob/main/CONTRIBUTING.md), [PROJECT GOVERNANCE](https://github.com/PowerGridModel/.github/blob/main/GOVERNANCE.md) and [RELEASE](https://github.com/PowerGridModel/.github/blob/main/RELEASE.md) for details on the process
 for submitting pull requests to us.
 
 Visit [Contribute](https://github.com/PowerGridModel/power-grid-model/contribute) for a list of good first issues in this repo.

docs/advanced_documentation/c-api.md

@@ -7,18 +7,18 @@ SPDX-License-Identifier: MPL-2.0
 # Use Power Grid Model through C API
 
 While many users use Python API for Power Grid Model.
-This library also provides a C API. 
-The main use case of C API is to integrate Power Grid Model into a non-Python application/library, namely, C, C++, JAVA, C#, etc. 
+This library also provides a C API.
+The main use case of C API is to integrate Power Grid Model into a non-Python application/library, namely, C, C++, JAVA, C#, etc.
 
-The C API consists of some 
+The C API consists of some
 {{ "[header files]({}/power_grid_model_c/power_grid_model_c/include)".format(gh_link_head_blob) }}
-and a dynamic library (`.so` or `.dll`) built by a 
+and a dynamic library (`.so` or `.dll`) built by a
 {{ "[cmake project]({}/power_grid_model_c/power_grid_model_c/CMakeLists.txt)".format(gh_link_head_blob) }}.
 Please refer to the [Build Guide](./build-guide.md) about how to build the library.
 
 You can refer to the [C API Reference](../api_reference/power-grid-model-c-api-reference.rst)
-for a detailed documentation of the API. 
-Please also have a look at an 
+for a detailed documentation of the API.
+Please also have a look at an
 {{ "[example]({}/power_grid_model_c_example/main.c)".format(gh_link_head_blob) }}
 of C program to use this C API.
 
@@ -37,7 +37,7 @@ and making it available to their binaries, e.g. by adding its location to `PATH`
 
 ## Opaque struct/pointer
 
-As a common C API practice, we use [opaque struct/pointer](https://en.wikipedia.org/wiki/Opaque_pointer) in the API. 
+As a common C API practice, we use [opaque struct/pointer](https://en.wikipedia.org/wiki/Opaque_pointer) in the API.
 The user creates the object by `PGM_create_*` function and release the object by `PGM_destroy_*` function.
 In other function calls, the user provide the relevant opaque pointer as the argument.
 The real memory layout of the object is unknown to the user.
@@ -50,21 +50,21 @@ Moreover, we might want to also retrieve some meta information from the calculat
 The C API uses a handle opaque object `PGM_Handle` to store all these kinds of error messages and information.
 You need to pass a handle pointer to most of the functions in the C API.
 
-For example, after calling `PGM_create_model`, you can use `PGM_error_code` and `PGM_error_message` 
+For example, after calling `PGM_create_model`, you can use `PGM_error_code` and `PGM_error_message`
 to check if there is error during the creation and the error message.
 
 If you are calling the C API in multiple threads, each thread should have its own handle object created by `PGM_create_handle`.
 
 ## Calculation options
 
-To execute a power grid calculation you need to specify many options, 
+To execute a power grid calculation you need to specify many options,
 e.g., maximum number of iterations, error tolerance, etc.
 We could have declared all the calculation options as individual arguments in the `PGM_calculate` function.
-However, due to the lack of default argument in C, 
+However, due to the lack of default argument in C,
 this would mean that the C API has a breaking change everytime we add a new option,
 which happends very often.
 
-To solve this issue, we use another opaque object `PGM_Options`. The user creates an object with default options by `PGM_create_options`. You can then specify individual options by `PGM_set_*`. 
+To solve this issue, we use another opaque object `PGM_Options`. The user creates an object with default options by `PGM_create_options`. You can then specify individual options by `PGM_set_*`.
 In the `PGM_calculate` function you need to pass a pointer to `PGM_Options`.
 In this way, we can ensure the API backwards compatibility.
 If we add a new option, it will get a default value in the `PGM_create_options` function.
@@ -77,7 +77,7 @@ For compatibility reasons, that format is dictated by the C API using the `PGM_m
 
 We define the following concepts in the data hierarchy:
 
-* Dataset: a collection of data buffers for a given purpose. 
+* Dataset: a collection of data buffers for a given purpose.
   At this moment, we have four dataset types: `input`, `update`, `sym_output`, `asym_output`.
 * Component: a data buffer with the representation of all attributes of a physical grid component in our [data model](../user_manual/components.md), e.g., `node`.
 * Attribute: a property of given component. For example, `u_rated` attribute of `node` is the rated voltage of the node.
@@ -126,7 +126,7 @@ Data buffers are almost always allocated and freed in the heap. We provide two w
 
 * You can use the function `PGM_create_buffer` and `PGM_destroy_buffer` to create and destroy buffer.
   In this way, the library is handling the memory (de-)allocation.
-* You can call some memory (de-)allocation function in your own code according to your platform, 
+* You can call some memory (de-)allocation function in your own code according to your platform,
   e.g., `aligned_alloc` and `free`.
   You need to first call `PGM_meta_*` functions to retrieve the size and alignment of a component.
 
@@ -141,10 +141,10 @@ Once you have the data buffer, you need to set or get attributes. We provide two
 
 * You can use the function `PGM_buffer_set_value` and `PGM_buffer_get_value` to get and set values.
 * You can do pointer cast directly on the buffer pointer, by shifting the pointer to proper offset
-  and cast it to a certain value type. 
+  and cast it to a certain value type.
   You need to first call `PGM_meta_*` functions to retrieve the correct offset.
 
-Pointer cast is generally more efficient and flexible because you are not calling into the 
+Pointer cast is generally more efficient and flexible because you are not calling into the
 dynamic library everytime. But it requires the user to retrieve the offset information first.
 Using the buffer helper function is more convenient but with some overhead.
 
@@ -153,7 +153,7 @@ Using the buffer helper function is more convenient but with some overhead.
 In the C API we have a function `PGM_buffer_set_nan` which sets all the attributes in a buffer to `NaN`.
 In the calculation core, if an optional attribute is `NaN`, it will use the default value.
 
-If you just want to set some attributes and keep everything else as `NaN`, 
+If you just want to set some attributes and keep everything else as `NaN`,
 calling `PGM_buffer_set_nan` before you set attribute is convenient.
 This is useful especially in `update` dataset because you do not always update all the mutable attributes.