make-ki · Oct 17, 2026
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -61,7 +61,7 @@ if(${PGM_ENABLE_DEV_BUILD})
     # get tests
     add_subdirectory("tests")
     # get c api example
-    add_subdirectory("power_grid_model_c_example")
+    add_subdirectory("examples/c_api")
 endif()
 
 # export the power grid model

diff --git a/docs/advanced_documentation/build-guide.md b/docs/advanced_documentation/build-guide.md
@@ -214,7 +214,7 @@ In the developer build the following build targets (directories) are enabled:
 * `tests/cpp_validation_tests`: the validation test target using the `doctest` framework.
 * `tests/native_api_tests`: the C API test target using the `doctest` framework.
 * `tests/benchmark_cpp`: the C++ benchmark target for performance measure.
-* `power_grid_model_c_example`: an example C program to call the dynamic library.
+* `examples/c_api`: example C programs to call the dynamic library.
 
 On Linux/macOS, the presets will use command `clang`/`clang++` or `gcc`/`g++` to find the relevant `clang` or `gcc`
 compiler.

diff --git a/docs/advanced_documentation/c-api.md b/docs/advanced_documentation/c-api.md
@@ -19,7 +19,7 @@ Please refer to the [Build Guide](./build-guide.md) about how to build the libra
 
 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 {{ "[example]({}/power_grid_model_c_example/main.c)".format(gh_link_head_blob) }} of C
+Please also have a look at an {{ "[example]({}/examples/c_api/main.c)".format(gh_link_head_blob) }} of C
 program to use this C API.
 
 In this documentation, the main design choices and concepts of the C API are presented.
@@ -65,7 +65,7 @@ Logging incurs a performance cost and its output may change between releases.
 The logger lifecycle is: create with `PGM_create_logger`, register with `PGM_register_logger`, run calculations, read
 the output with `PGM_logger_get_output`, optionally clear it with `PGM_logger_clear_content`, unregister with
 `PGM_unregister_logger`, and destroy it with `PGM_destroy_logger`. The
-{{ "[logging example]({}/power_grid_model_c_example/logging.c)".format(gh_link_head_blob) }} demonstrates this flow.
+{{ "[logging example]({}/examples/c_api/logging.c)".format(gh_link_head_blob) }} demonstrates this flow.
 
 `PGM_logger_get_output` delivers the output to its callback as a pointer and a byte count. The data is not
 null-terminated and is valid only for the callback, so use the supplied size rather than C string functions. 

diff --git a/docs/contribution/folder-structure.md b/docs/contribution/folder-structure.md
@@ -12,8 +12,9 @@ The repository folder structure is as follows. The `docs` and `scripts` folders
   {{ "[power_grid_model_c/power_grid_model/include/power_grid_model]({}/power_grid_model_c/power_grid_model/include/power_grid_model)".format(gh_link_head_tree) }}.  
 - The C API is inside
   {{ "[power_grid_model_c/power_grid_model_c]({}/power_grid_model_c/power_grid_model_c)".format(gh_link_head_tree) }}.
-- The C program example to use the C API is inside
-  {{ "[power_grid_model_c_example]({}/power_grid_model_c_example)".format(gh_link_head_tree) }}.
+- The C program examples to use the C API are inside
+  {{ "[examples/c_api]({}/examples/c_api)".format(gh_link_head_tree) }}.
+- The Jupyter example notebooks are inside `docs/example_notebooks/`.
 - The python interface code is in {{ "[src/power_grid_model]({}/src/power_grid_model)".format(gh_link_head_tree) }}
 - The code for validation of input data is in
   {{ "[validation]({}/src/power_grid_model/validation)".format(gh_link_head_tree) }} folder.

diff --git a/...ples/Asymmetric Calculation Example.ipynb → ...ooks/Asymmetric Calculation Example.ipynb b/...ples/Asymmetric Calculation Example.ipynb → ...ooks/Asymmetric Calculation Example.ipynb
diff --git a/...mmetric Calculation Example.ipynb.license → ...mmetric Calculation Example.ipynb.license b/...mmetric Calculation Example.ipynb.license → ...mmetric Calculation Example.ipynb.license
diff --git a/docs/examples/Asymmetric Line.ipynb → docs/example_notebooks/Asymmetric Line.ipynb b/docs/examples/Asymmetric Line.ipynb → docs/example_notebooks/Asymmetric Line.ipynb
diff --git a/docs/examples/Asymmetric Line.ipynb.license → ...e_notebooks/Asymmetric Line.ipynb.license b/docs/examples/Asymmetric Line.ipynb.license → ...e_notebooks/Asymmetric Line.ipynb.license
diff --git a/docs/examples/Generic Branch Example.ipynb → ...le_notebooks/Generic Branch Example.ipynb b/docs/examples/Generic Branch Example.ipynb → ...le_notebooks/Generic Branch Example.ipynb
diff --git a/...ples/Generic Branch Example.ipynb.license → ...ooks/Generic Branch Example.ipynb.license b/...ples/Generic Branch Example.ipynb.license → ...ooks/Generic Branch Example.ipynb.license
diff --git a/docs/examples/Logging Example.ipynb → docs/example_notebooks/Logging Example.ipynb b/docs/examples/Logging Example.ipynb → docs/example_notebooks/Logging Example.ipynb
diff --git a/docs/examples/Logging Example.ipynb.license → ...e_notebooks/Logging Example.ipynb.license b/docs/examples/Logging Example.ipynb.license → ...e_notebooks/Logging Example.ipynb.license
diff --git a/docs/examples/Make Test Dataset.ipynb → ...example_notebooks/Make Test Dataset.ipynb b/docs/examples/Make Test Dataset.ipynb → ...example_notebooks/Make Test Dataset.ipynb
diff --git a/.../examples/Make Test Dataset.ipynb.license → ...notebooks/Make Test Dataset.ipynb.license b/.../examples/Make Test Dataset.ipynb.license → ...notebooks/Make Test Dataset.ipynb.license
diff --git a/...mensional batch calculation example.ipynb → ...mensional batch calculation example.ipynb b/...mensional batch calculation example.ipynb → ...mensional batch calculation example.ipynb
@@ -14,7 +14,7 @@
     "\n",
     "It is possible to conduct a batch calculation of multiple datasets in form of a cartesian product of their scenarios. Assume certain batch datasets with $N1$, $N2$, $N3$, … scenarios. This would give us $N1 * N2 *N3 ...$ possible combinations via the cartesian product. The resulting output data is in flat form, with dimension of $N1 * N2 *N3 ...$, where the first dataset has the highest dimension. This can be beneficial in reducing the complexity of implementing such a batch calculation along with keeping the size of such resulting update_data to a minimum.\n",
     "\n",
-    "**Note: For a more comprehensive description, see our [documentation](https://power-grid-model.readthedocs.io/en/stable/user_manual/calculations.html#cartesian-product-of-batch-datasets). For a more detailed guide on how to use this feature, see our [powerflow](https://power-grid-model.readthedocs.io/en/stable/examples/Power%20Flow%20Example.html#cartesian-product-of-batch-datasets) and [validation](https://power-grid-model.readthedocs.io/en/stable/examples/Validation%20Examples.html#validating-cartesian-product-of-batch-datasets) examples.**\n",
+    "**Note: For a more comprehensive description, see our [documentation](https://power-grid-model.readthedocs.io/en/stable/user_manual/calculations.html#cartesian-product-of-batch-datasets). For a more detailed guide on how to use this feature, see our [powerflow](https://power-grid-model.readthedocs.io/en/stable/example_notebooks/Power%20Flow%20Example.html#cartesian-product-of-batch-datasets) and [validation](https://power-grid-model.readthedocs.io/en/stable/example_notebooks/Validation%20Examples.html#validating-cartesian-product-of-batch-datasets) examples.**\n",
     "\n",
     "\n",
     "## Example Network\n",

diff --git a/...l batch calculation example.ipynb.license → ...l batch calculation example.ipynb.license b/...l batch calculation example.ipynb.license → ...l batch calculation example.ipynb.license
diff --git a/docs/examples/Power Flow Example.ipynb → ...xample_notebooks/Power Flow Example.ipynb b/docs/examples/Power Flow Example.ipynb → ...xample_notebooks/Power Flow Example.ipynb
diff --git a/...examples/Power Flow Example.ipynb.license → ...otebooks/Power Flow Example.ipynb.license b/...examples/Power Flow Example.ipynb.license → ...otebooks/Power Flow Example.ipynb.license
diff --git a/docs/examples/Serialization Example.ipynb → ...ple_notebooks/Serialization Example.ipynb b/docs/examples/Serialization Example.ipynb → ...ple_notebooks/Serialization Example.ipynb
diff --git a/...mples/Serialization Example.ipynb.license → ...books/Serialization Example.ipynb.license b/...mples/Serialization Example.ipynb.license → ...books/Serialization Example.ipynb.license
diff --git a/docs/examples/Short Circuit Example.ipynb → ...ple_notebooks/Short Circuit Example.ipynb b/docs/examples/Short Circuit Example.ipynb → ...ple_notebooks/Short Circuit Example.ipynb
diff --git a/...mples/Short Circuit Example.ipynb.license → ...books/Short Circuit Example.ipynb.license b/...mples/Short Circuit Example.ipynb.license → ...books/Short Circuit Example.ipynb.license
diff --git a/docs/examples/State Estimation Example.ipynb → ..._notebooks/State Estimation Example.ipynb b/docs/examples/State Estimation Example.ipynb → ..._notebooks/State Estimation Example.ipynb
diff --git a/...es/State Estimation Example.ipynb.license → ...ks/State Estimation Example.ipynb.license b/...es/State Estimation Example.ipynb.license → ...ks/State Estimation Example.ipynb.license
diff --git a/docs/examples/Transformer Examples.ipynb → ...mple_notebooks/Transformer Examples.ipynb b/docs/examples/Transformer Examples.ipynb → ...mple_notebooks/Transformer Examples.ipynb
diff --git a/...amples/Transformer Examples.ipynb.license → ...ebooks/Transformer Examples.ipynb.license b/...amples/Transformer Examples.ipynb.license → ...ebooks/Transformer Examples.ipynb.license
diff --git a/docs/examples/Validation Examples.ipynb → ...ample_notebooks/Validation Examples.ipynb b/docs/examples/Validation Examples.ipynb → ...ample_notebooks/Validation Examples.ipynb
diff --git a/...xamples/Validation Examples.ipynb.license → ...tebooks/Validation Examples.ipynb.license b/...xamples/Validation Examples.ipynb.license → ...tebooks/Validation Examples.ipynb.license
diff --git a/docs/examples/data/serialized_input.json → ...mple_notebooks/data/serialized_input.json b/docs/examples/data/serialized_input.json → ...mple_notebooks/data/serialized_input.json
diff --git a/...amples/data/serialized_input.json.license → ...ebooks/data/serialized_input.json.license b/...amples/data/serialized_input.json.license → ...ebooks/data/serialized_input.json.license
diff --git a/docs/index.md b/docs/index.md
@@ -110,18 +110,18 @@ api_reference/power-grid-model-c-api-reference
 ```{toctree}
 :caption: "Examples"
 :maxdepth: 2
-examples/Power Flow Example.ipynb
-examples/Serialization Example.ipynb
-examples/State Estimation Example.ipynb
-examples/Short Circuit Example.ipynb
-examples/Multi-dimensional batch calculation example.ipynb
-examples/Validation Examples.ipynb
-examples/Make Test Dataset.ipynb
-examples/Asymmetric Calculation Example.ipynb
-examples/Transformer Examples.ipynb
-examples/Generic Branch Example.ipynb
-examples/Asymmetric Line.ipynb
-examples/Logging Example.ipynb
+example_notebooks/Power Flow Example.ipynb
+example_notebooks/Serialization Example.ipynb
+example_notebooks/State Estimation Example.ipynb
+example_notebooks/Short Circuit Example.ipynb
+example_notebooks/Multi-dimensional batch calculation example.ipynb
+example_notebooks/Validation Examples.ipynb
+example_notebooks/Make Test Dataset.ipynb
+example_notebooks/Asymmetric Calculation Example.ipynb
+example_notebooks/Transformer Examples.ipynb
+example_notebooks/Generic Branch Example.ipynb
+example_notebooks/Asymmetric Line.ipynb
+example_notebooks/Logging Example.ipynb
 ```
 
 ```{toctree}

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -98,7 +98,7 @@ input_data = {
 ```
 
 Another example of how to create components can be found in
-[Input data](examples/Power%20Flow%20Example.ipynb#input-dataset).
+[Input data](example_notebooks/Power%20Flow%20Example.ipynb#input-dataset).
 
 ```{note}
 The keys of the dictonary of arrays are unique and should match with the respective `type name` of the component.
@@ -160,5 +160,5 @@ Refer to [Data Validator](user_manual/data-validator) for more details.
 You can calculate a (large) number of scenarios using one command and even in parallel threading.
 This is what makes Power Grid Model a powerful calculation engine.
 You need to create a batch update dataset and put it in the `update_data` argument of `calculate_power_flow`.
-Please refer to [Power Flow Example](examples/Power%20Flow%20Example.ipynb) for a detailed tutorial about how to execute
+Please refer to [Power Flow Example](example_notebooks/Power%20Flow%20Example.ipynb) for a detailed tutorial about how to execute
 batch calculations.
diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md
@@ -14,13 +14,13 @@ With power-grid-model it is possible to perform three different types of calcula
   This calculation can be performed by using the
   {py:class}`calculate_power_flow <power_grid_model.PowerGridModel.calculate_power_flow>` method.
   An example of usage of the power-flow calculation function is given in
-  [Power flow Example](../examples/Power%20Flow%20Example.ipynb)
+  [Power flow Example](../example_notebooks/Power%20Flow%20Example.ipynb)
 - [State estimation](#state-estimation-algorithms): a statistical method that calculates the most probabilistic state of
   the grid, given sensor values with an uncertainty.
   This calculation can be performed by using the
   {py:class}`calculate_state_estimation <power_grid_model.PowerGridModel.calculate_state_estimation>` method.
   An example of usage of the power-flow calculation function is given in
-  [State Estimation Example](../examples/State%20Estimation%20Example.ipynb)
+  [State Estimation Example](../example_notebooks/State%20Estimation%20Example.ipynb)
 - [Short circuit](#short-circuit-calculation-algorithms): a "what-if" scenario calculation with short circuit entries.
   This calculation can be performed by using the
   {py:class}`calculate_short_circuit <power_grid_model.PowerGridModel.calculate_short_circuit>` method.
@@ -426,7 +426,7 @@ The framework for creating the batches is the same for all types of calculations
 For every component, the attributes that can be updated in a batch scenario are mentioned in
 [Components](components.md).
 Examples of batch calculations for timeseries and contingency analysis are given in
-[Power Flow Example](../examples/Power%20Flow%20Example.ipynb)
+[Power Flow Example](../example_notebooks/Power%20Flow%20Example.ipynb)
 
 The same method as for single calculations, {py:class}`power_grid_model.PowerGridModel.calculate_power_flow`, can be
 used to calculate a number of scenarios in one go.

diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md
@@ -33,7 +33,7 @@ Uniform component updates are ones that update the same number of component of t
 By definition, a dense update is always uniform, hence the IDs can always be optional; whereas for a sparse update, the
 IDs can only be optional if the index pointer is given as an arithmetic sequence of all elements (i.e. a sparse
 representation of a dense buffer).
-An example of the usage of optional IDs is given in [Power Flow Example](./Power%20Flow%20Example.ipynb)
+An example of the usage of optional IDs is given in [Power Flow Example](../example_notebooks/Power%20Flow%20Example.ipynb)
 
 #### Steady state output and Short circuit output
 
@@ -235,7 +235,7 @@ $$
 
 `transformer` is a [branch](#branch) which connects two nodes with possibly different
 voltage levels.
-An example of usage of transformer is given in [Transformer Examples](../examples/Transformer%20Examples.ipynb)
+An example of usage of transformer is given in [Transformer Examples](../example_notebooks/Transformer%20Examples.ipynb)
 
 #### Input
 
@@ -560,7 +560,7 @@ In reality such switches may not exist.
 `three_winding_transformer` is a [branch3](#branch3) connects three nodes with possibly
 different voltage levels.
 An example of usage of three-winding transformer is given in
-[Transformer Examples](../examples/Transformer%20Examples.ipynb).
+[Transformer Examples](../example_notebooks/Transformer%20Examples.ipynb).
 
 #### Input
 

diff --git a/docs/user_manual/data-validator.md b/docs/user_manual/data-validator.md
@@ -14,7 +14,7 @@ will raise exceptions, most of them wil just yield invalid results without warni
 The main validation functions and classes can be included from `power_grid_model.validation`.
 
 ```{seealso}
-Check the [example](examples/Validation%20Examples.ipynb) for an example of function applications.
+Check the [example](../example_notebooks/Validation%20Examples.ipynb) for an example of function applications.
 ```
 
 ## Validation Errors

diff --git a/docs/user_manual/model-validation.md b/docs/user_manual/model-validation.md
@@ -305,4 +305,4 @@ A similar example is also recreated for validation with the R state estimation p
 ## Test case creation
 
 Contribution to power-grid-model is also possible by creating own test cases in similar format.
-A guide for exporting the input or output data is given in [Make Test Dataset](../examples/Make%20Test%20Dataset.ipynb).
+A guide for exporting the input or output data is given in [Make Test Dataset](../example_notebooks/Make%20Test%20Dataset.ipynb).
diff --git a/docs/user_manual/non-native-components.md b/docs/user_manual/non-native-components.md
@@ -198,7 +198,7 @@ Automatic tap control via the transformer tap regulator is not available for `ge
 ```
 
 A use case of `generic_branch` as PST can be found in
-[Generic Branch Example](../examples/Generic%20Branch%20Example.ipynb).
+[Generic Branch Example](../example_notebooks/Generic%20Branch%20Example.ipynb).
 
 ## Choke coil
 

diff --git a/docs/user_manual/performance-guide.md b/docs/user_manual/performance-guide.md
@@ -65,7 +65,7 @@ This may or may not induce a slight computational overhead during calculations.
 Some simulations might require a Cartesian product of scenarios of two batch datasets.
 This can be done by passing them to `update_data` as a list
 ie. a list[{py:class}`BatchDataset <power_grid_model.data_types.BatchDataset>`]
-(Check [Power Flow Example](../examples/Power%20Flow%20Example.ipynb)).
+(Check [Power Flow Example](../example_notebooks/Power%20Flow%20Example.ipynb)).
 This gets treated as a Cartesian product of the provided datasets and the combination of scenarios gets handled
 internally.
 Hence there is no need to allocate memory for full `N1 * N2 * ...` scenarios for a Cartesian product of data sets with

diff --git a/power_grid_model_c_example/CMakeLists.txt → examples/c_api/CMakeLists.txt b/power_grid_model_c_example/CMakeLists.txt → examples/c_api/CMakeLists.txt
@@ -12,7 +12,10 @@ target_link_libraries(
 )
 
 add_executable(power_grid_model_c_example_logging logging.c)
-target_link_libraries(power_grid_model_c_example_logging PRIVATE power_grid_model_c)
+target_link_libraries(
+    power_grid_model_c_example_logging
+    PRIVATE power_grid_model_c
+)
 
 add_test(
     PGMExample

diff --git a/power_grid_model_c_example/logging.c → examples/c_api/logging.c b/power_grid_model_c_example/logging.c → examples/c_api/logging.c
diff --git a/power_grid_model_c_example/main.c → examples/c_api/main.c b/power_grid_model_c_example/main.c → examples/c_api/main.c
diff --git a/power_grid_model_c_example/serialization.c → examples/c_api/serialization.c b/power_grid_model_c_example/serialization.c → examples/c_api/serialization.c
diff --git a/pyproject.toml b/pyproject.toml
@@ -187,7 +187,7 @@ combine-as-imports = true
 
 [tool.ruff.lint.per-file-ignores]
 # Ignore `F811` (redefinition violations) in all examples notebooks since we use redefinition.
-"docs/examples/*.ipynb" = ["F811", "E402"]
+"docs/example_notebooks/*.ipynb" = ["F811", "E402"]
 # Pylint was only run in src directory before moving to Ruff
 "tests/*" = ["PLR0915", "PLR0912", "PLR0913", "S"]
 # Ignore private member access: _model_ptr, _all_component_count...