Skip to content

Commit a14b074

Browse files
mgoversmgovers
authored
Merge pull request #1006 from PowerGridModel/feature/document-undefined-behavior
Documentation: add advanced programming terminology documentation
2 parents 27b1629 + 2119219 commit a14b074

File tree

3 files changed

+340
-1
lines changed

3 files changed

+340
-1
lines changed

‎docs/advanced_documentation/terminology.md

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
<!--
2+
SPDX-FileCopyrightText: Contributors to the Power Grid Model project <[email protected]>
3+
4+
SPDX-License-Identifier: MPL-2.0
5+
-->
6+
7+
# Advanced terminology
8+
9+
The power grid model is a large project with many assumptions, as well as design and implementation choices.
10+
It combines deep electrical engineering knowledge and modeling with physics, mathematics and programming.
11+
All those fields of expertises also come with their own terminology.
12+
In an attempt to ease communication between experts from different fields, this section contains a (non-exhaustive)
13+
glossary of the terminology used within the power grid model knowledge base.
14+
15+
```{contents}
16+
```
17+
18+
## Programming terminology
19+
20+
### Bug
21+
22+
A bug is a problem with the code, in the sense that the code behaves differently from the intended behavior.
23+
Examples are crashes, incorrectly raising exceptions and incorrect results.
24+
We take bugs very seriously, and will try to fix them as soon as possible.
25+
If you find a bug, or expect to have found one, please report it.
26+
We will respond as soon as possible.
27+
28+
Depending on the nature and impact of the bug, we will post announcements via our
29+
[mailing list](https://lists.lfenergy.org/g/powergridmodel).
30+
31+
#### Security vulnerability
32+
33+
These bugs are the most severe type of bugs, as they may give attackers access to data, secrets or controls they would
34+
otherwise not have access to.
35+
Due to the nature of the power grid model as a library, it does not directly interface with the outside world, like a
36+
REST API can do.
37+
Only attackers that already have illegitimate access to the data or system can affect the results, but no more than they
38+
would otherwise have without the use of the library.
39+
40+
That said, the power grid model still contains a number of critical points that deserve special attention of the user of
41+
the power grid model - although no more than any other library:
42+
43+
* The C API is a native data interface. Although the power grid model can check whether the input contain null-pointers
44+
(`nullptr`/`NULL`/`0` values where they are not allowed) and can act accordingly, it is not possible to check whether
45+
a non-null pointer was actually valid.
46+
The behavior of the power grid model in such cases is [undefined](#undefined-behavior-ub-as-a-bug).
47+
This is also true for any other native interface that deals with pointers.
48+
It is the users' responsibility to provide correct input data.
49+
See also [below](#bad-input).
50+
* If the input data provided to the power grid model is incorrect, the power grid model cannot guarantee that it will be
51+
able to find and handle that correctly.
52+
The behavior is [undefined](#undefined-behavior-ub-as-a-bug).
53+
This is also true for any other interface, including native data interfaces.
54+
[It is the users' responsibility](https://en.wikipedia.org/wiki/Garbage_in,_garbage_out) to provide correct input
55+
data.
56+
See also [below](#bad-input).
57+
58+
#### Incorrect results
59+
60+
These bugs are the second most severe kind, as they directly impact users without reporting them.
61+
They may remain hidden until they resurface in a completely different location.
62+
Encountering such bugs may result in wrong decisions in control logic or incorrect conclusions in scientific research.
63+
64+
We take these bugs very seriously.
65+
If you encounter them, please report them.
66+
We will always post announcements regarding bugs of this nature.
67+
68+
#### Nonsensical results
69+
70+
Sometimes, bugs in the code can cause clearly nonsensical results, like not-a-number (NaN/`np.nan`)
71+
values in the output.
72+
Like in the case of [incorrect results](#incorrect-results), no exceptions are raised (if there were, it would not be a
73+
bug of this type) and therefore may be hidden for a long time until they first appear.
74+
However, they are easy to detect, especially in production environments with (real-time) monitoring and other tools,
75+
programs and libraries that do their own error handling.
76+
77+
Their visibility makes solving them usually easy.
78+
If you encounter them, please report them.
79+
We will usually post announcements regarding bugs of this nature.
80+
81+
#### Undefined behavior bugs
82+
83+
See also [below](#undefined-behavior-ub-as-a-bug).
84+
85+
Although the power grid model takes all the care it can in preventing
86+
[undefined behavior](#undefined-behavior-ub-as-a-bug) like infinite loops or extreme blow-up of the data usage, it is
87+
still possible that such behavior exists in the code.
88+
If you find any such issues, please report the issue and we will fix them as soon as possible.
89+
90+
#### Incorrect exceptions
91+
92+
Sometimes, exceptions are raised when they should not be.
93+
For example, a `NotObservableError` that is raised when the current scenario actually contains an observable grid, would
94+
be a bug.
95+
They can be a headache to users, because it is difficult to know whether the exception was caused by
96+
[bad data](#bad-input) or by a power grid model bug, even for the power grid model maintainers.
97+
98+
If you find any such issues, please report the issue and explicitly mention that you suspect a bug in the power grid
99+
model, together with a reasoning as to why you think so.
100+
That way, the maintainers can take extra care to investigate before coming back to you with an answer.
101+
102+
#### Incorrect/outdated documentation
103+
104+
The power grid model maintainers will always try to keep the documentation up-to-date.
105+
However, it is always possible that sections of the documentation become outdated.
106+
Please help us keep our documentation up-to-date by reporting and/or fixing issues.
107+
108+
### Bad input
109+
110+
This is a problem with the input data.
111+
They cannot be considered bugs in the power grid model and instead are the users' responsibility.
112+
113+
In certain cases, the [data validator](../user_manual/data-validator.md) can catch data issues.
114+
However, it is not guaranteed to provide an exhaustive check.
115+
116+
#### Unsupported input
117+
118+
The power grid model explicitly forbids certain (combinations of) values.
119+
For example, a negative `u_rated` on a node is not allowed.
120+
Unsupported input will always be documented in the power grid model documentation.
121+
122+
Checking every single combination of input parameters would come at a significant performance cost.
123+
In addition, for most use cases, incorrect input data happens mostly during the development phase of a user workflow.
124+
In production environments, when performance is usually important, the data is usually already sanitized and can be
125+
assumed to be correct.
126+
Because of this, assuring the
127+
[correctness of the input data is the users' responsibility](https://en.wikipedia.org/wiki/Garbage_in,_garbage_out).
128+
129+
However, most data errors of this kind can be found using the [data validator](../user_manual/data-validator.md).
130+
131+
#### Incorrect input
132+
133+
The power grid model assumes that the input data is correct.
134+
Of course, the power grid model cannot know whether a user provided the grid correctly.
135+
For example, if the user adds a source to the wrong node, the power grid model can only obey.
136+
137+
Input correctness is entirely the users' responsibility.
138+
The [power-grid-model-ds visualiser](https://power-grid-model-ds.readthedocs.io/en/stable/visualizer.html) may provide
139+
some tools to help with the investigation.
140+
141+
#### Unreasonable input
142+
143+
The power grid model assumes that the input data is correct and makes assumptions about typical use cases of the grid
144+
based on electrical engineering expert knowledge.
145+
For instance, while a line with an impedance of $10^{-50}\,\Omega$ is mathematically possible, it does not make sense
146+
from an electrical engineering point of view.
147+
Making the calculations mathematically stable under such extreme situations would come at an excessive temporal and
148+
spatial performance cost.
149+
150+
The threshold of what can and cannot be considered "reasonable" is a vague gray area, potentially spanning multiple
151+
orders of magnitude.
152+
As a result, it is possible that the assumptions of the power grid model are currently too restrictive.
153+
If you have a use case for which the power grid model currently does not provide the correct results as a consequence of
154+
such optimizations, please consider [contributing](../user_manual/model-validation.md#test-case-creation) or reporting
155+
the use case.
156+
It may be possible to improve the behavior in such edge cases, like we did for
157+
[sources with large `sk`](https://github.com/PowerGridModel/power-grid-model/issues/458).
158+
159+
Adding support for previously unsupported edge cases due to this type of assumptions is considered a new feature.
160+
161+
#### Experimental features
162+
163+
Experimental features are features that are still under development.
164+
The behavior of the power grid model is [undefined](#undefined-behavior) when experimental features are used.
165+
The data validator and/or documentation may not capture all the supported and unsupported values for the data.
166+
167+
We do not guarantee anything concerning experimental features and using and enabling them is entirely up to the user.
168+
Any input regarding experimental features is always appreciated.
169+
170+
### Edge case
171+
172+
A scenario in which the behavior of the program changes significantly when one or more parameters change slightly.
173+
Examples include the following.
174+
175+
* The input value `0` when taking the square root of a floating point:
176+
* A positive value will result in valid output data
177+
* A negative value will result in not-a-number values (NaN/`np.nan`); spurious
178+
* Saddle-points in equations with many local optima may result in different optima, e.g.:
179+
* Different local optima (not spurious)
180+
* Short-circuit solutions (spurious)
181+
* Divergent domain (spurious)
182+
* Differences in amount of iterations before convergence is reached (not spurious)
183+
184+
#### Non-spurious edge cases
185+
186+
In non-spurious edge cases, the current behavior of the power grid model is actually correct.
187+
188+
Many edge cases are inherent to the problem statement are not necessarily bugs.
189+
For instance, if it takes a large number of iterations before a solution is found in an iterative calculation method,
190+
that is probably annoying and something that can be improved on, but not it is not necessarily directly a real issue
191+
with the implementation.
192+
Even if you encounter `IterationDiverge` errors, in many cases, increasing the error tolerance and/or maximum number of
193+
iterations may fix your problem.
194+
195+
Some edge cases may be input data errors.
196+
Please always double-check that the data is valid before reporting an issue, e.g., by running our
197+
[data validator](../user_manual/data-validator.md).
198+
Please also check whether your input data is correctly created and contains no obvious errors like sensors that are
199+
marked as measuring a node while, in fact, they are actually measuring branch flow.
200+
201+
Other examples of non-spurious edge cases are cases in which the power grid model reports a `NotObservableError`.
202+
203+
#### Spurious edge cases
204+
205+
Some edge cases are actual problems with the code.
206+
Some of them may be easy to solve, while others may be extremely difficult to find and/or resolve.
207+
Occasionally, even, more research is still needed before a satisfactory fix to the edge case can be found.
208+
An example of the latter is shown in [this paper](https://doi.org/10.48550/arXiv.2504.11650), which was published as
209+
collaboration between ICT for industy and power grid model.
210+
211+
#### Resolving edge cases
212+
213+
If you encounter any edge case, please double-check your data quality, e.g., by running our
214+
[data validator](../user_manual/data-validator.md) and verifying that the source of your data is
215+
up-to-date and correct.
216+
Please also try things like increasing the error tolerance or the number of iterations (when applicable) to see if that
217+
solves your issue.
218+
If it doesn't, the problem you found may be a bug in the power grid model.
219+
220+
If you encounter such edge cases and are sure that the current behavior is [incorrect](#spurious-edge-cases), please
221+
consider [contributing your findings](../user_manual/model-validation.md#test-case-creation) to help us improve the
222+
power grid model.
223+
224+
### Undefined behavior
225+
226+
A class of behavior of the code that is considered erroneous usage.
227+
[cppreference.com](https://en.cppreference.com/w/cpp/language/ub.html) describes undefined behavior (UB) as follows.
228+
229+
> Renders the entire program meaningless if certain rules of the language are violated. [...]
230+
231+
This is opposed to observable behavior, which it describes as follows.
232+
233+
> The C++ standard precisely defines the observable behavior of every C++ program that does not fall
234+
> into one of the [undefined behavior] classes.
235+
236+
#### Classes of UB
237+
238+
There are a number of classes of UB.
239+
We try to follow the [conventions of the C++ standard](https://en.cppreference.com/w/cpp/language/ub.html) as much as
240+
possible.
241+
Here is a summary of the classes relevant to end-users, i.e, we omit things like syntax errors.
242+
243+
##### Implementation-defined
244+
245+
The behavior of the program may differ between versions of the power grid model, compilers, versions of the standard
246+
library, platforms and architectures, usually intentionally.
247+
248+
Precision falls in this category, as differences between versions of the power grid model may introduce small deviations
249+
(e.g., rounding or truncation) that propagate.
250+
251+
Other examples include the [native data interface](native-data-interface.md), which, by design, depends on the platform
252+
and architecture.
253+
254+
Most effects on the results introduced by implementation-defined behavior are small.
255+
However, in the case of [edge cases](#edge-case), a small difference may result in completely different outcomes.
256+
257+
Unfortunately, there is not much that the power grid model can do make the implementation-defined behavior more
258+
consistent, except catching those edge cases that are easy to catch, like taking the square root of a negative number.
259+
260+
##### Unspecified behavior
261+
262+
The behavior of the program varies between implementations, and the conforming implementation is not required to
263+
document the effects of each behavior.
264+
Examples are the internal implementation, features that are still under development/experimental and the contents of the
265+
output of failing scenarios if exceptions were thrown and `continue_on_batch_error=True`.
266+
267+
Encountering unspecified behavior is considered a problem with the user input.
268+
269+
Unspecified behavior shall **never** be considered a bug from a user point of view.
270+
The developers may change the behavior at any time without notice.
271+
For example, a new exception may be thrown that changes the behavior from unspecified behavior to specified
272+
exception-throwing.
273+
274+
**NOTE:** PRs changing unspecified behavior may still be marked as a bugfix PR, if developers consider the previous
275+
behavior unexpected and/or undesirable.
276+
Examples are fixes to the behavior of a new feature that is still experimental/under development, but for which the
277+
developers thought that the behavior was already correctly implemented, before they found out that it was not.
278+
279+
##### Undefined behavior (subclass)
280+
281+
Undefined behavior is also a particular subclass of the superset of all undefined behavior that is defined as follows:
282+
283+
> There are no restrictions on the behavior of the program.
284+
285+
Examples include if a C API user provides an invalid pointer to the power grid model C API.
286+
While the C API can still compare and handle null-pointer (`nullptr`/`NULL`/`0`) values, it has no way of knowing what
287+
will happen if the user provides a non-null pointer to the wrong memory location.
288+
289+
Encountering undefined behavior (subclass) may result in crashes (but not necessarily),
290+
[security vulnerabilities](#undefined-behavior-bugs), or anything else.
291+
It is a common misconception that the OS will take care of such edge cases by crashing fatally.
292+
It is not required to do so and the behavior may even change case-by-case.
293+
294+
#### Undefined behavior (UB) as a feature
295+
296+
The power grid model attempts to define its API as future-proof as possible.
297+
Designing it well helps in maintaining backwards compatibility, stability and an optimal user experience without being
298+
in the way of adding new features.
299+
That means that decisions regarding some edge-case behavior need to be postponed until it is needed to make a decision
300+
on it.
301+
Defining such cases as [undefined behavior](#undefined-behavior) enables this.
302+
The following example illustrates this.
303+
304+
The power grid model uses enum values to set discrete options.
305+
The list of supported enum values may be extended at a later stage (e.g., to support a new calculation type).
306+
Consider the `enum A { a = 0, b = 1 };`.
307+
308+
* If the behavior is _defined_ to throw an error if any other value is supplied, then it will never be possible to
309+
extend the enum with new options, because doing so would be a breaking change.
310+
* On the other hand, if the behavior is [_unspecified_](#unspecified-behavior) and the current behavior "just so happens
311+
to be" that it throws an error if another value is supplied, then it is still possible to at a later date without
312+
changing previously _defined_ behavior.
313+
314+
In the second case, the fact that the original behavior was [_unspecified_](#unspecified-behavior) enabled future
315+
compatibility while still providing useful feedback to the user that an unsupported option was provided.
316+
317+
This example shows that undefined behavior is not necessarily bad - it just needs to be handled with care.
318+
It does so by explicitly creating a boundary between what is the program's responsibility and what is the users'.
319+
320+
#### Undefined behavior (UB) as a bug
321+
322+
Triggering undefined behavior is a potential source for [security vulnerabilities](#undefined-behavior-bugs) and should
323+
therefore be avoided.
324+
Triggering undefined behavior should always be conidered a bug, regardless of whether it is caused by an incorrect
325+
internal implementation of the power grid model or a result of incorrect usage by a user.
326+
327+
To help both users and maintainers to find incorrect usage of and bugs in the power grid model, it uses an error
328+
handling mechanism.
329+
It also has extended assertion checks in Debug build configuration used in test and development environments to prevent
330+
internal bugs.
331+
332+
To prevent, find and fix harder-to-find instances of undefined behavior, the power grid model uses tools like
333+
AddressSanitizer and SonarQube Cloud.
334+
We strongly recommend all users to do the same - especially the ones using the C API.
335+
336+
If you find or expect any undefined behavior, please report it and/or
337+
[contribute](../user_manual/model-validation.md#test-case-creation) with a reproducible case, as doing so helps
338+
improving the quality and user experience of the power grid model.

‎docs/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,7 @@ advanced_documentation/c-api
117117
advanced_documentation/high-level-design
118118
advanced_documentation/core-design
119119
advanced_documentation/python-wrapper-design
120+
advanced_documentation/terminology
120121
```
121122

122123
```{toctree}

‎docs/user_manual/components.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,7 @@ There is no additional attribute for `link`.
169169

170170
#### Electric Model
171171

172-
`link` is modeled by a constant reactance $Y_{\text{series}}$, where
172+
`link` is modeled by a constant admittance $Y_{\text{series}}$, where
173173

174174
$$
175175
\begin{eqnarray}

0 commit comments

Comments
 (0)