You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
2
+
#
3
+
# SPDX-License-Identifier: MPL-2.0
4
+
5
+
# 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
6
+
MD001: false
7
+
8
+
# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md
9
+
MD013: false
10
+
# # Number of characters
11
+
# line_length: 80
12
+
# # Number of characters for headings
13
+
# heading_line_length: 80
14
+
# # Number of characters for code blocks
15
+
# code_block_line_length: 80
16
+
# # Include code blocks
17
+
# code_blocks: true
18
+
# # Include tables
19
+
# tables: true
20
+
# # Include headings
21
+
# headings: true
22
+
# # Strict length checking
23
+
# strict: false
24
+
# # Stern length checking
25
+
# stern: false
26
+
27
+
# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md024.md
[](#)<!-- markdownlint-disable-line no-empty-links -->
28
28
29
29
# Power Grid Model
30
30
@@ -50,15 +50,15 @@ Want to be updated on the latest news and releases? Subscribe to the Power Grid
50
50
51
51
You can directly install the package from PyPI.
52
52
53
-
```
53
+
```sh
54
54
pip install power-grid-model
55
55
```
56
56
57
57
### Install from Conda
58
58
59
59
If you are using `conda`, you can directly install the package from `conda-forge` channel.
60
60
61
-
```
61
+
```sh
62
62
conda install -c conda-forge power-grid-model
63
63
```
64
64
@@ -68,7 +68,7 @@ To install the library from source, refer to the [Build Guide](https://power-gri
68
68
69
69
## Examples
70
70
71
-
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.
71
+
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.
72
72
Notebooks for validating the input data and exporting input/output data are also included.
73
73
74
74
## License
@@ -77,14 +77,14 @@ This project is licensed under the Mozilla Public License, version 2.0 - see [LI
77
77
78
78
## Licenses third-party libraries
79
79
80
-
This project includes third-party libraries,
80
+
This project includes third-party libraries,
81
81
which are licensed under their own respective Open-Source licenses.
82
-
SPDX-License-Identifier headers are used to show which license is applicable.
82
+
SPDX-License-Identifier headers are used to show which license is applicable.
83
83
The concerning license files can be found in the [LICENSES](https://github.com/PowerGridModel/power-grid-model/tree/main/LICENSES) directory.
84
84
85
85
## Contributing
86
86
87
-
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
87
+
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
88
88
for submitting pull requests to us.
89
89
90
90
Visit [Contribute](https://github.com/PowerGridModel/power-grid-model/contribute) for a list of good first issues in this repo.
@@ -37,7 +37,7 @@ and making it available to their binaries, e.g. by adding its location to `PATH`
37
37
38
38
## Opaque struct/pointer
39
39
40
-
As a common C API practice, we use [opaque struct/pointer](https://en.wikipedia.org/wiki/Opaque_pointer) in the API.
40
+
As a common C API practice, we use [opaque struct/pointer](https://en.wikipedia.org/wiki/Opaque_pointer) in the API.
41
41
The user creates the object by `PGM_create_*` function and release the object by `PGM_destroy_*` function.
42
42
In other function calls, the user provide the relevant opaque pointer as the argument.
43
43
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
50
50
The C API uses a handle opaque object `PGM_Handle` to store all these kinds of error messages and information.
51
51
You need to pass a handle pointer to most of the functions in the C API.
52
52
53
-
For example, after calling `PGM_create_model`, you can use `PGM_error_code` and `PGM_error_message`
53
+
For example, after calling `PGM_create_model`, you can use `PGM_error_code` and `PGM_error_message`
54
54
to check if there is error during the creation and the error message.
55
55
56
56
If you are calling the C API in multiple threads, each thread should have its own handle object created by `PGM_create_handle`.
57
57
58
58
## Calculation options
59
59
60
-
To execute a power grid calculation you need to specify many options,
60
+
To execute a power grid calculation you need to specify many options,
61
61
e.g., maximum number of iterations, error tolerance, etc.
62
62
We could have declared all the calculation options as individual arguments in the `PGM_calculate` function.
63
-
However, due to the lack of default argument in C,
63
+
However, due to the lack of default argument in C,
64
64
this would mean that the C API has a breaking change everytime we add a new option,
65
65
which happends very often.
66
66
67
-
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_*`.
67
+
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_*`.
68
68
In the `PGM_calculate` function you need to pass a pointer to `PGM_Options`.
69
69
In this way, we can ensure the API backwards compatibility.
70
70
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
77
77
78
78
We define the following concepts in the data hierarchy:
79
79
80
-
* Dataset: a collection of data buffers for a given purpose.
80
+
* Dataset: a collection of data buffers for a given purpose.
81
81
At this moment, we have four dataset types: `input`, `update`, `sym_output`, `asym_output`.
82
82
* 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`.
83
83
* 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
126
126
127
127
* You can use the function `PGM_create_buffer` and `PGM_destroy_buffer` to create and destroy buffer.
128
128
In this way, the library is handling the memory (de-)allocation.
129
-
* You can call some memory (de-)allocation function in your own code according to your platform,
129
+
* You can call some memory (de-)allocation function in your own code according to your platform,
130
130
e.g., `aligned_alloc` and `free`.
131
131
You need to first call `PGM_meta_*` functions to retrieve the size and alignment of a component.
132
132
@@ -141,10 +141,10 @@ Once you have the data buffer, you need to set or get attributes. We provide two
141
141
142
142
* You can use the function `PGM_buffer_set_value` and `PGM_buffer_get_value` to get and set values.
143
143
* You can do pointer cast directly on the buffer pointer, by shifting the pointer to proper offset
144
-
and cast it to a certain value type.
144
+
and cast it to a certain value type.
145
145
You need to first call `PGM_meta_*` functions to retrieve the correct offset.
146
146
147
-
Pointer cast is generally more efficient and flexible because you are not calling into the
147
+
Pointer cast is generally more efficient and flexible because you are not calling into the
148
148
dynamic library everytime. But it requires the user to retrieve the offset information first.
149
149
Using the buffer helper function is more convenient but with some overhead.
150
150
@@ -153,7 +153,7 @@ Using the buffer helper function is more convenient but with some overhead.
153
153
In the C API we have a function `PGM_buffer_set_nan` which sets all the attributes in a buffer to `NaN`.
154
154
In the calculation core, if an optional attribute is `NaN`, it will use the default value.
155
155
156
-
If you just want to set some attributes and keep everything else as `NaN`,
156
+
If you just want to set some attributes and keep everything else as `NaN`,
157
157
calling `PGM_buffer_set_nan` before you set attribute is convenient.
158
158
This is useful especially in `update` dataset because you do not always update all the mutable attributes.
0 commit comments