Merge pull request #1473 from PowerGridModel/pgm/feature/document-oom-errors

Docs: add known limitation clause on running out of memory

Author: TonyXiang8787

docs/advanced_documentation/c-api.md

@@ -225,3 +225,15 @@ A writable dataset, instead, cannot be created by the user, but will be provided
 The user can then provide buffers to which the deserializer can write its data (and `indptr`).
 This allows the buffers to have lifetimes beyond the lifetime of the deserializer.
 This dataset type is only meant to be used for providing user buffers to the deserializer.
+
+## Known limitations
+
+The current serialization functionality has some limitations.
+
+### Memory limitations
+
+Hardware limitations and availability of free contiguous memory may result in, e.g., failing buffer allocation.
+Often, this will lead to a [`bad_alloc`](https://en.cppreference.com/cpp/memory/new/bad_alloc).
+Due to the nature of the issue, we consider this a [non-spurious edge case](./terminology.md#non-spurious-edge-cases).
+Wherever possible, the Power Grid Model catches and wraps such low-level exceptions.
+Regardlessly, caution is still adviced when handling large datasets.

docs/advanced_documentation/terminology.md

@@ -221,7 +221,10 @@ Please always double-check that the data is valid before reporting an issue, e.g
 Please also check whether your input data is correctly created and contains no obvious errors like sensors that are
 marked as measuring a node while, in fact, they are actually measuring branch flow.
 
-Other examples of non-spurious edge cases are cases in which the power grid model reports a `NotObservableError`.
+Other examples of non-spurious edge cases are:
+
+* Cases in which the power grid model reports a `NotObservableError`;
+* Cases in which a `PowerGridError` is thrown that wraps a `bad_alloc` (running out of available contiguous memory).
 
 #### Spurious edge cases
 

docs/user_manual/serialization.md

@@ -406,3 +406,15 @@ The type is listed for each attribute in [Components](components.md).
 
 **NOTE:** the special value `nan` represents absence of value and may also be represented by
 [`nil`](#msgpack-schema-nil-absence-of-value) in the [msgpack schema](#msgpack-serialization-format-specification).
+
+## Known limitations
+
+The current serialization functionality has some limitations.
+
+### Memory limitations
+
+Hardware limitations and availability of free contiguous memory may result in failing serialization and deserialization.
+Often, this will lead to a [`bad_alloc`](https://en.cppreference.com/cpp/memory/new/bad_alloc).
+Due to the nature of the issue, we consider this a [non-spurious edge case](./terminology.md#non-spurious-edge-cases).
+Wherever possible, the Power Grid Model catches and wraps such low-level exceptions thrown during (de-)serialization.
+Regardlessly, caution is still adviced when handling large datasets.