From ec452ec22ab1d8b3507f1c5835e88698e592c70e Mon Sep 17 00:00:00 2001 From: Anupam Mishra Date: Sat, 17 Oct 2026 20:55:08 +0530 Subject: [PATCH 1/4] Reorganize API examples and documentation notebooks Signed-off-by: Anupam Mishra --- CMakeLists.txt | 2 +- docs/advanced_documentation/build-guide.md | 2 +- docs/advanced_documentation/c-api.md | 4 ++-- docs/contribution/folder-structure.md | 5 ++-- .../Asymmetric Calculation Example.ipynb | 0 ...ymmetric Calculation Example.ipynb.license | 0 .../Asymmetric Line.ipynb | 0 .../Asymmetric Line.ipynb.license | 0 .../Generic Branch Example.ipynb | 0 .../Generic Branch Example.ipynb.license | 0 .../Logging Example.ipynb | 0 .../Logging Example.ipynb.license | 0 .../Make Test Dataset.ipynb | 0 .../Make Test Dataset.ipynb.license | 0 ...imensional batch calculation example.ipynb | 2 +- ...al batch calculation example.ipynb.license | 0 .../Power Flow Example.ipynb | 0 .../Power Flow Example.ipynb.license | 0 .../Serialization Example.ipynb | 0 .../Serialization Example.ipynb.license | 0 .../Short Circuit Example.ipynb | 0 .../Short Circuit Example.ipynb.license | 0 .../State Estimation Example.ipynb | 0 .../State Estimation Example.ipynb.license | 0 .../Transformer Examples.ipynb | 0 .../Transformer Examples.ipynb.license | 0 .../Validation Examples.ipynb | 0 .../Validation Examples.ipynb.license | 0 .../data/serialized_input.json | 0 .../data/serialized_input.json.license | 0 docs/index.md | 24 +++++++++---------- docs/quickstart.md | 4 ++-- docs/user_manual/calculations.md | 6 ++--- docs/user_manual/components.md | 6 ++--- docs/user_manual/data-validator.md | 2 +- docs/user_manual/model-validation.md | 2 +- docs/user_manual/non-native-components.md | 2 +- docs/user_manual/performance-guide.md | 2 +- .../c_api}/CMakeLists.txt | 5 +++- .../c_api}/logging.c | 0 .../c_api}/main.c | 0 .../c_api}/serialization.c | 0 pyproject.toml | 2 +- 43 files changed, 37 insertions(+), 33 deletions(-) rename docs/{examples => example_notebooks}/Asymmetric Calculation Example.ipynb (100%) rename docs/{examples => example_notebooks}/Asymmetric Calculation Example.ipynb.license (100%) rename docs/{examples => example_notebooks}/Asymmetric Line.ipynb (100%) rename docs/{examples => example_notebooks}/Asymmetric Line.ipynb.license (100%) rename docs/{examples => example_notebooks}/Generic Branch Example.ipynb (100%) rename docs/{examples => example_notebooks}/Generic Branch Example.ipynb.license (100%) rename docs/{examples => example_notebooks}/Logging Example.ipynb (100%) rename docs/{examples => example_notebooks}/Logging Example.ipynb.license (100%) rename docs/{examples => example_notebooks}/Make Test Dataset.ipynb (100%) rename docs/{examples => example_notebooks}/Make Test Dataset.ipynb.license (100%) rename docs/{examples => example_notebooks}/Multi-dimensional batch calculation example.ipynb (98%) rename docs/{examples => example_notebooks}/Multi-dimensional batch calculation example.ipynb.license (100%) rename docs/{examples => example_notebooks}/Power Flow Example.ipynb (100%) rename docs/{examples => example_notebooks}/Power Flow Example.ipynb.license (100%) rename docs/{examples => example_notebooks}/Serialization Example.ipynb (100%) rename docs/{examples => example_notebooks}/Serialization Example.ipynb.license (100%) rename docs/{examples => example_notebooks}/Short Circuit Example.ipynb (100%) rename docs/{examples => example_notebooks}/Short Circuit Example.ipynb.license (100%) rename docs/{examples => example_notebooks}/State Estimation Example.ipynb (100%) rename docs/{examples => example_notebooks}/State Estimation Example.ipynb.license (100%) rename docs/{examples => example_notebooks}/Transformer Examples.ipynb (100%) rename docs/{examples => example_notebooks}/Transformer Examples.ipynb.license (100%) rename docs/{examples => example_notebooks}/Validation Examples.ipynb (100%) rename docs/{examples => example_notebooks}/Validation Examples.ipynb.license (100%) rename docs/{examples => example_notebooks}/data/serialized_input.json (100%) rename docs/{examples => example_notebooks}/data/serialized_input.json.license (100%) rename {power_grid_model_c_example => examples/c_api}/CMakeLists.txt (89%) rename {power_grid_model_c_example => examples/c_api}/logging.c (100%) rename {power_grid_model_c_example => examples/c_api}/main.c (100%) rename {power_grid_model_c_example => examples/c_api}/serialization.c (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 711b87706f..087bc28285 100644 --- 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 index 9984dc077d..74ca3747d2 100644 --- 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 index 2b9e42da1a..e4ff2b7e3a 100644 --- 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 index 752d1bf5e7..30e6702da8 100644 --- 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/docs/examples/Asymmetric Calculation Example.ipynb b/docs/example_notebooks/Asymmetric Calculation Example.ipynb similarity index 100% rename from docs/examples/Asymmetric Calculation Example.ipynb rename to docs/example_notebooks/Asymmetric Calculation Example.ipynb diff --git a/docs/examples/Asymmetric Calculation Example.ipynb.license b/docs/example_notebooks/Asymmetric Calculation Example.ipynb.license similarity index 100% rename from docs/examples/Asymmetric Calculation Example.ipynb.license rename to docs/example_notebooks/Asymmetric Calculation Example.ipynb.license diff --git a/docs/examples/Asymmetric Line.ipynb b/docs/example_notebooks/Asymmetric Line.ipynb similarity index 100% rename from docs/examples/Asymmetric Line.ipynb rename to docs/example_notebooks/Asymmetric Line.ipynb diff --git a/docs/examples/Asymmetric Line.ipynb.license b/docs/example_notebooks/Asymmetric Line.ipynb.license similarity index 100% rename from docs/examples/Asymmetric Line.ipynb.license rename to docs/example_notebooks/Asymmetric Line.ipynb.license diff --git a/docs/examples/Generic Branch Example.ipynb b/docs/example_notebooks/Generic Branch Example.ipynb similarity index 100% rename from docs/examples/Generic Branch Example.ipynb rename to docs/example_notebooks/Generic Branch Example.ipynb diff --git a/docs/examples/Generic Branch Example.ipynb.license b/docs/example_notebooks/Generic Branch Example.ipynb.license similarity index 100% rename from docs/examples/Generic Branch Example.ipynb.license rename to docs/example_notebooks/Generic Branch Example.ipynb.license diff --git a/docs/examples/Logging Example.ipynb b/docs/example_notebooks/Logging Example.ipynb similarity index 100% rename from docs/examples/Logging Example.ipynb rename to docs/example_notebooks/Logging Example.ipynb diff --git a/docs/examples/Logging Example.ipynb.license b/docs/example_notebooks/Logging Example.ipynb.license similarity index 100% rename from docs/examples/Logging Example.ipynb.license rename to docs/example_notebooks/Logging Example.ipynb.license diff --git a/docs/examples/Make Test Dataset.ipynb b/docs/example_notebooks/Make Test Dataset.ipynb similarity index 100% rename from docs/examples/Make Test Dataset.ipynb rename to docs/example_notebooks/Make Test Dataset.ipynb diff --git a/docs/examples/Make Test Dataset.ipynb.license b/docs/example_notebooks/Make Test Dataset.ipynb.license similarity index 100% rename from docs/examples/Make Test Dataset.ipynb.license rename to docs/example_notebooks/Make Test Dataset.ipynb.license diff --git a/docs/examples/Multi-dimensional batch calculation example.ipynb b/docs/example_notebooks/Multi-dimensional batch calculation example.ipynb similarity index 98% rename from docs/examples/Multi-dimensional batch calculation example.ipynb rename to docs/example_notebooks/Multi-dimensional batch calculation example.ipynb index 761e358e05..836e31c382 100644 --- a/docs/examples/Multi-dimensional batch calculation example.ipynb +++ b/docs/example_notebooks/Multi-dimensional 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/docs/examples/Multi-dimensional batch calculation example.ipynb.license b/docs/example_notebooks/Multi-dimensional batch calculation example.ipynb.license similarity index 100% rename from docs/examples/Multi-dimensional batch calculation example.ipynb.license rename to docs/example_notebooks/Multi-dimensional batch calculation example.ipynb.license diff --git a/docs/examples/Power Flow Example.ipynb b/docs/example_notebooks/Power Flow Example.ipynb similarity index 100% rename from docs/examples/Power Flow Example.ipynb rename to docs/example_notebooks/Power Flow Example.ipynb diff --git a/docs/examples/Power Flow Example.ipynb.license b/docs/example_notebooks/Power Flow Example.ipynb.license similarity index 100% rename from docs/examples/Power Flow Example.ipynb.license rename to docs/example_notebooks/Power Flow Example.ipynb.license diff --git a/docs/examples/Serialization Example.ipynb b/docs/example_notebooks/Serialization Example.ipynb similarity index 100% rename from docs/examples/Serialization Example.ipynb rename to docs/example_notebooks/Serialization Example.ipynb diff --git a/docs/examples/Serialization Example.ipynb.license b/docs/example_notebooks/Serialization Example.ipynb.license similarity index 100% rename from docs/examples/Serialization Example.ipynb.license rename to docs/example_notebooks/Serialization Example.ipynb.license diff --git a/docs/examples/Short Circuit Example.ipynb b/docs/example_notebooks/Short Circuit Example.ipynb similarity index 100% rename from docs/examples/Short Circuit Example.ipynb rename to docs/example_notebooks/Short Circuit Example.ipynb diff --git a/docs/examples/Short Circuit Example.ipynb.license b/docs/example_notebooks/Short Circuit Example.ipynb.license similarity index 100% rename from docs/examples/Short Circuit Example.ipynb.license rename to docs/example_notebooks/Short Circuit Example.ipynb.license diff --git a/docs/examples/State Estimation Example.ipynb b/docs/example_notebooks/State Estimation Example.ipynb similarity index 100% rename from docs/examples/State Estimation Example.ipynb rename to docs/example_notebooks/State Estimation Example.ipynb diff --git a/docs/examples/State Estimation Example.ipynb.license b/docs/example_notebooks/State Estimation Example.ipynb.license similarity index 100% rename from docs/examples/State Estimation Example.ipynb.license rename to docs/example_notebooks/State Estimation Example.ipynb.license diff --git a/docs/examples/Transformer Examples.ipynb b/docs/example_notebooks/Transformer Examples.ipynb similarity index 100% rename from docs/examples/Transformer Examples.ipynb rename to docs/example_notebooks/Transformer Examples.ipynb diff --git a/docs/examples/Transformer Examples.ipynb.license b/docs/example_notebooks/Transformer Examples.ipynb.license similarity index 100% rename from docs/examples/Transformer Examples.ipynb.license rename to docs/example_notebooks/Transformer Examples.ipynb.license diff --git a/docs/examples/Validation Examples.ipynb b/docs/example_notebooks/Validation Examples.ipynb similarity index 100% rename from docs/examples/Validation Examples.ipynb rename to docs/example_notebooks/Validation Examples.ipynb diff --git a/docs/examples/Validation Examples.ipynb.license b/docs/example_notebooks/Validation Examples.ipynb.license similarity index 100% rename from docs/examples/Validation Examples.ipynb.license rename to docs/example_notebooks/Validation Examples.ipynb.license diff --git a/docs/examples/data/serialized_input.json b/docs/example_notebooks/data/serialized_input.json similarity index 100% rename from docs/examples/data/serialized_input.json rename to docs/example_notebooks/data/serialized_input.json diff --git a/docs/examples/data/serialized_input.json.license b/docs/example_notebooks/data/serialized_input.json.license similarity index 100% rename from docs/examples/data/serialized_input.json.license rename to docs/example_notebooks/data/serialized_input.json.license diff --git a/docs/index.md b/docs/index.md index e0bcfa9f80..569150ed16 100644 --- 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 index f0976861c4..81af23d25f 100644 --- 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 index 9935d1bf61..f3cb5f5505 100644 --- 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 ` 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 ` 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 ` 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 index 411b300bef..c626ede675 100644 --- 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 index 5389b80a50..4cc16221f0 100644 --- 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 index 6a7be1d762..899b8be9ba 100644 --- 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 index a06772b3ce..39a1c2c4cc 100644 --- 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 index c4f1bf122a..e9678962fd 100644 --- 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 `] -(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 b/examples/c_api/CMakeLists.txt similarity index 89% rename from power_grid_model_c_example/CMakeLists.txt rename to examples/c_api/CMakeLists.txt index f0cf376270..a5e6977f28 100644 --- a/power_grid_model_c_example/CMakeLists.txt +++ b/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 b/examples/c_api/logging.c similarity index 100% rename from power_grid_model_c_example/logging.c rename to examples/c_api/logging.c diff --git a/power_grid_model_c_example/main.c b/examples/c_api/main.c similarity index 100% rename from power_grid_model_c_example/main.c rename to examples/c_api/main.c diff --git a/power_grid_model_c_example/serialization.c b/examples/c_api/serialization.c similarity index 100% rename from power_grid_model_c_example/serialization.c rename to examples/c_api/serialization.c diff --git a/pyproject.toml b/pyproject.toml index 6e208a2010..50d9d32a0a 100644 --- 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... From f01a04ed636d026070bc7d1c975858a13fb95d84 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Mon, 19 Oct 2026 10:32:05 +0200 Subject: [PATCH 2/4] Update docs/contribution/folder-structure.md Signed-off-by: Martijn Govers Signed-off-by: Martijn Govers --- docs/contribution/folder-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribution/folder-structure.md b/docs/contribution/folder-structure.md index 30e6702da8..ed1ebb0762 100644 --- a/docs/contribution/folder-structure.md +++ b/docs/contribution/folder-structure.md @@ -14,7 +14,7 @@ The repository folder structure is as follows. The `docs` and `scripts` folders {{ "[power_grid_model_c/power_grid_model_c]({}/power_grid_model_c/power_grid_model_c)".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 Jupyter example notebooks are inside {{ "[docs/example_notebooks/]({}/examples/c_api)".format(gh_link_head_tree) }}. - 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. From 748b65834024db595436cd9b1a0f71d393846c2b Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Mon, 19 Oct 2026 10:41:59 +0200 Subject: [PATCH 3/4] Apply suggestion from @mgovers Signed-off-by: Martijn Govers Signed-off-by: Martijn Govers --- docs/contribution/folder-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribution/folder-structure.md b/docs/contribution/folder-structure.md index ed1ebb0762..f2b59d8efb 100644 --- a/docs/contribution/folder-structure.md +++ b/docs/contribution/folder-structure.md @@ -14,7 +14,7 @@ The repository folder structure is as follows. The `docs` and `scripts` folders {{ "[power_grid_model_c/power_grid_model_c]({}/power_grid_model_c/power_grid_model_c)".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/]({}/examples/c_api)".format(gh_link_head_tree) }}. +- The Jupyter example notebooks are inside {{ "[docs/example_notebooks/]({}/docs/example_notebooks)".format(gh_link_head_tree) }}. - 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. From a5014e417651e41458b52e9dbd1a0c6fcd6b0361 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Mon, 19 Oct 2026 10:46:10 +0200 Subject: [PATCH 4/4] Apply suggestion from @mgovers Signed-off-by: Martijn Govers Signed-off-by: Martijn Govers --- docs/advanced_documentation/c-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced_documentation/c-api.md b/docs/advanced_documentation/c-api.md index e4ff2b7e3a..b8167476ac 100644 --- a/docs/advanced_documentation/c-api.md +++ b/docs/advanced_documentation/c-api.md @@ -19,8 +19,8 @@ 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]({}/examples/c_api/main.c)".format(gh_link_head_blob) }} of C -program to use this C API. +Please also have a look at the {{ "[C API examples]({}/examples/c_api/)".format(gh_link_head_blob) }}, +like {{ "[this example]({}/examples/c_api/main.c)".format(gh_link_head_blob) }} for basic C API usage. In this documentation, the main design choices and concepts of the C API are presented.