|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org> |
| 3 | +
|
| 4 | +SPDX-License-Identifier: MPL-2.0 |
| 5 | +--> |
| 6 | + |
| 7 | +# High-level design |
| 8 | + |
| 9 | +The power-grid-model follows a typical dynamic/shared library approach, in which the user |
| 10 | +interface is separated from the core implementation using a strict system boundary. Depending |
| 11 | +on the use case and programming language used by the user to call the interface, the user can |
| 12 | +opt to interface with the C API in different ways. |
| 13 | + |
| 14 | +## Layers of abstraction |
| 15 | + |
| 16 | +For the sake of explanation, we consider the |
| 17 | +following layers of abstraction, in increasing order of ease-of-use and abstraction. |
| 18 | + |
| 19 | +* Raw system interface |
| 20 | + * System symbols only |
| 21 | + * Everything is handled by the user, including which symbols are supported |
| 22 | +* Exposition-only |
| 23 | + * Exposes the supported symbols in a language supported by the user |
| 24 | + * Memory management and error handling is the responsibility of the user |
| 25 | +* Simple wrapper |
| 26 | + * Wraps the interface in a language supported by the user |
| 27 | + * Handles memory management, basic error handling and type conversions |
| 28 | + * Contains no additional features except maybe some basic utility tools |
| 29 | +* The feature-rich layer |
| 30 | + * Extensive wrapper around the interface with easy functionality exposure and utility functions |
| 31 | + * Extensive type checks |
| 32 | + |
| 33 | +## Existing library interfaces |
| 34 | + |
| 35 | +The following library interfaces are currently included in the power-grid-model. |
| 36 | + |
| 37 | +| Interface type | Status | Layer | Explanation | Supported by | |
| 38 | +| -------------- | ------------ | ------------------ | --------------------------------------------------------------- | --------------------------------------------------- | |
| 39 | +| C API | Stable | Raw interface | Shared object / DLL that contains the core implementation | All programming languages with dynamic load support | |
| 40 | +| C headers | Stable | Exposition-only | Exposition-only library using dynamic linking | C and C++ | |
| 41 | +| C++ headers | Experimental | Wrapper | Handles memory management and basic error handling | C++ | |
| 42 | +| Python library | Stable | Feature-rich layer | Library with useful functions, conversions and extensive checks | Python | |
| 43 | + |
| 44 | +Note that the Python library in turn also follows the pattern of a feature-rich library that uses a |
| 45 | +module-internal wrapper layer core module, that wraps the exposition-only core module, that exposes |
| 46 | +the raw interface. |
| 47 | + |
| 48 | +This can be visualized graphically as follows. |
| 49 | + |
| 50 | +```{mermaid} |
| 51 | + :title: Full design |
| 52 | +
|
| 53 | +flowchart TD |
| 54 | + classDef user_node fill:#9f6,stroke:#333,stroke-width:2px |
| 55 | + classDef public_interface fill:#69f,stroke:#333,stroke-width:2px |
| 56 | + classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px |
| 57 | + classDef private_interface fill:#999,stroke:#333,stroke-width:2px |
| 58 | + classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px |
| 59 | +
|
| 60 | + subgraph User |
| 61 | + any_language_user(["Any language user"]):::user_node |
| 62 | + c_user(["C user"]):::user_node |
| 63 | + cpp_user(["C++ user"]):::user_node |
| 64 | + python_user(["Python user"]):::user_node |
| 65 | + end |
| 66 | +
|
| 67 | + dynamic_loading{ }:::inclusion_method |
| 68 | + c_includes{ }:::inclusion_method |
| 69 | +
|
| 70 | + subgraph Raw interface |
| 71 | + power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface |
| 72 | + end |
| 73 | +
|
| 74 | + subgraph Exposition |
| 75 | + power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface |
| 76 | + power_grid_core_python("power_grid_model._core<br>.power_grid_core.py<br>(exposition-only<br>Python module)"):::private_interface |
| 77 | + end |
| 78 | +
|
| 79 | + subgraph Wrapper |
| 80 | + power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface |
| 81 | + power_grid_model_core_python("power_grid_model._core<br>(Python wrapper library)"):::private_interface |
| 82 | + end |
| 83 | +
|
| 84 | + subgraph Feature-rich library |
| 85 | + power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface |
| 86 | + end |
| 87 | +
|
| 88 | + any_language_user --> dynamic_loading |
| 89 | + c_includes --> dynamic_loading |
| 90 | + dynamic_loading -->|dynamic loading| power_grid_model_c_dll |
| 91 | + c_user --> c_includes |
| 92 | + cpp_user --> c_includes |
| 93 | + c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll |
| 94 | + cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c |
| 95 | + python_user -->|import| power_grid_model_python -->|internal import| power_grid_model_core_python -->|internal import| power_grid_core_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll |
| 96 | +``` |
| 97 | + |
| 98 | +## Creating a custom library or interface |
| 99 | + |
| 100 | +We seek to provide an optimal user experience, but with the sheer amount of programming languages and |
| 101 | +features, it would be impossible to provide a full feature-rich library for every single one. We, |
| 102 | +being a {{ "[community-driven]({}/GOVERNANCE.md)".format(pgm_project_contribution) }} project strongly in |
| 103 | +favor of modern software engineering practices, therefore encourage people to create their own |
| 104 | +libraries and interfaces to improve their own experience. There are several possible reasons a user |
| 105 | +may want to create their own library or interface, e.g.: |
| 106 | + |
| 107 | +* Support for a new programming language |
| 108 | +* Extending library support for a specific programming language |
| 109 | +* A custom wrapper that provides extra features or useful commands for specific custom requirements |
| 110 | + |
| 111 | +In all cases, it is recommended that the user determines their own desired |
| 112 | +[layer of abstraction](#layers-of-abstraction) and then creates internal wrappers for all |
| 113 | +lower-level ones, following the same pattern as the power-grid-model |
| 114 | +[uses internally](#existing-library-interfaces) for the custom interfaces. |
| 115 | + |
| 116 | +### Hosting a custom library or interface |
| 117 | + |
| 118 | +The Power Grid Model organization supports people creating and hosting custom libraries and |
| 119 | +interfaces. If you are doing so and are willing to notify us, please create an item on our |
| 120 | +[discussion board](https://github.com/orgs/PowerGridModel/discussions) on GitHub. The Power Grid |
| 121 | +Model organization will review your item and we may decide to mention your custom library on our |
| 122 | +project website and documentation. |
| 123 | + |
| 124 | +### Contributing a custom library or interface |
| 125 | + |
| 126 | +When a custom library or interface becomes mature enough and the circumstances allow making it |
| 127 | +publicly available, please consider contributing it to the Power Grid Model organization. If you are |
| 128 | +considering contributing your custom library or interface, please read and follow our |
| 129 | +{{ "[contributing guidelines]({}/CONTRIBUTING.md)".format(pgm_project_contribution) }} and open an |
| 130 | +item on our [discussion board](https://github.com/orgs/PowerGridModel/discussions) on GitHub. The |
| 131 | +Power Grid Model organization will review your item and contact you accordingly. |
0 commit comments