power-grid-model 1.10.17__py3-none-win_amd64.whl → 1.12.119__py3-none-win_amd64.whl

power_grid_model/_core/power_grid_model_c/include/power_grid_model_c/handle.h

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+//
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @brief header file which includes handle functions
+ *
+ */
+
+#pragma once
+#ifndef POWER_GRID_MODEL_C_HANDLE_H
+#define POWER_GRID_MODEL_C_HANDLE_H
+
+#include "basics.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Create a new handle.
+ *
+ * A handle object is needed to store error information.
+ * If you run it in multi-threading at user side, each thread should have unique handle.
+ * The handle should be destroyed by PGM_destroy_handle().
+ *
+ * @return A pointer to the created handle.
+ */
+PGM_API PGM_Handle* PGM_create_handle(void);
+
+/**
+ * @brief Destroy the handle.
+ *
+ * @param handle The pointer to the handle created by PGM_create_handle().
+ */
+PGM_API void PGM_destroy_handle(PGM_Handle* handle);
+
+/**
+ * @brief Get error code of last operation.
+ *
+ * The behavior is implementation-defined if the handle is NULL.
+ *
+ * @param handle The pointer to the handle you just used for an operation.
+ * @return The error code, see #PGM_ErrorCode .
+ */
+PGM_API PGM_Idx PGM_error_code(PGM_Handle const* handle);
+
+/**
+ * @brief Get error message of last operation.
+ *
+ * If the error code is PGM_batch_error.
+ * Use PGM_n_failed_scenarios(), PGM_failed_scenarios(), and PGM_batch_errors() to retrieve the detail.
+ *
+ * The behavior is implementation-defined if the handle is NULL.
+ *
+ * @param handle The pointer to the handle you just used for an operation.
+ * @return A char const* poiner to a zero terminated string.
+ * The pointer is not valid if you execute another operation.
+ * You need to copy the string in your own data.
+ */
+PGM_API char const* PGM_error_message(PGM_Handle const* handle);
+
+/**
+ * @brief Get the number of failed scenarios. Only applicable when you just executed a batch calculation.
+ *
+ * The behavior is implementation-defined if the handle is NULL.
+ *
+ * @param handle The pointer to the handle you just used for a batch calculation.
+ * @return The number of failed scenarios.
+ */
+PGM_API PGM_Idx PGM_n_failed_scenarios(PGM_Handle const* handle);
+
+/**
+ * @brief Get the list of failed scenarios, Only applicable when you just execute a batch calculation.
+ *
+ * The behavior is implementation-defined if the handle is NULL.
+ *
+ * @param handle The pointer to the handle you just used for a batch calculation.
+ * @return A pointer to a PGM_Idx array with length returned by PGM_n_failed_scenarios().
+ * The pointer is not valid if you execute another operation.
+ * You need to copy the array in your own data.
+ */
+PGM_API PGM_Idx const* PGM_failed_scenarios(PGM_Handle const* handle);
+
+/**
+ * @brief Get the list of batch errors. Only applicable when you just execute a batch calculation.
+ *
+ * The behavior is implementation-defined if the handle is NULL.
+ *
+ * @param handle The pointer to the handle you just used for a batch calculation.
+ * @return A pointer to a char const* array with length returned by PGM_n_failed_scenarios().
+ * Each entry is a zero terminated string.
+ * The pointer is not valid if you execute another operation.
+ * You need to copy the array (and the string) in your own data.
+ */
+PGM_API char const** PGM_batch_errors(PGM_Handle const* handle);
+
+/**
+ * @brief Clear and reset the handle.
+ *
+ * The behavior is implementation-defined if the handle is NULL.
+ *
+ * @param handle The pointer to the handle.
+ */
+PGM_API void PGM_clear_error(PGM_Handle* handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

power_grid_model/_core/power_grid_model_c/include/power_grid_model_c/meta_data.h

@@ -0,0 +1,189 @@
+// SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+//
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @brief header file which includes meta data functions
+ *
+ */
+
+#pragma once
+#ifndef POWER_GRID_MODEL_C_META_DATA_H
+#define POWER_GRID_MODEL_C_META_DATA_H
+
+#include "basics.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Get number of datasets.
+ *
+ * @param handle
+ * @return The number of datasets.
+ */
+PGM_API PGM_Idx PGM_meta_n_datasets(PGM_Handle* handle);
+
+/**
+ * @brief Get pointer of idx-th dataset.
+ *
+ * @param handle
+ * @param idx The sequence number, should be between [0, PGM_meta_n_datasets()).
+ * @return The pointer to the idx-th dataset. The pointer is permanantly valid.
+ * Or a NULL if your input is out of bound.
+ */
+PGM_API PGM_MetaDataset const* PGM_meta_get_dataset_by_idx(PGM_Handle* handle, PGM_Idx idx);
+
+/**
+ * @brief Get pointer of dataset by name.
+ *
+ * @param handle
+ * @param dataset The name of the dataset.
+ * @return The pointer to the dataset with that name. The pointer is permanantly valid.
+ * Or a NULL if your input is out of bound.
+ */
+PGM_API PGM_MetaDataset const* PGM_meta_get_dataset_by_name(PGM_Handle* handle, char const* dataset);
+
+/**
+ * @brief Get name of the dataset.
+ *
+ * @param handle
+ * @param dataset The pointer to a dataset object.
+ * @return The name of the dataset in a char const*. The pointer is permanantly valid.
+ */
+PGM_API char const* PGM_meta_dataset_name(PGM_Handle* handle, PGM_MetaDataset const* dataset);
+
+/**
+ * @brief Get the number of components for a dataset.
+ *
+ * @param handle
+ * @param dataset The pointer to the dataset.
+ * @return Number of components.
+ */
+PGM_API PGM_Idx PGM_meta_n_components(PGM_Handle* handle, PGM_MetaDataset const* dataset);
+
+/**
+ * @brief Get pointer of idx-th component of a dataset.
+ *
+ * @param handle
+ * @param dataset The pointer to the dataset.
+ * @param idx The sequence number, should be between [0, PGM_meta_n_components()).
+ * @return The pointer to the idx-th component. The pointer is permanantly valid.
+ * Or a NULL if your input is out of bound.
+ */
+PGM_API PGM_MetaComponent const* PGM_meta_get_component_by_idx(PGM_Handle* handle, PGM_MetaDataset const* dataset,
+                                                               PGM_Idx idx);
+/**
+ * @brief Get pointer of a component by name.
+ *
+ * @param handle
+ * @param dataset The name of the dataset.
+ * @param component The name of the component.
+ * @return The pointer to the component with that name. The pointer is permanantly valid.
+ * Or a NULL if your input is out of bound.
+ */
+PGM_API PGM_MetaComponent const* PGM_meta_get_component_by_name(PGM_Handle* handle, char const* dataset,
+                                                                char const* component);
+
+/**
+ * @brief Get name of component.
+ *
+ * @param handle
+ * @param component The pointer to the component.
+ * @return The name of the component in a char const*. The pointer is permanantly valid.
+ */
+PGM_API char const* PGM_meta_component_name(PGM_Handle* handle, PGM_MetaComponent const* component);
+
+/**
+ * @brief Get size of the component.
+ *
+ * @param handle
+ * @param component The pointer to the component.
+ * @return Size of the component.
+ */
+PGM_API size_t PGM_meta_component_size(PGM_Handle* handle, PGM_MetaComponent const* component);
+
+/**
+ * @brief Get alignment of the component.
+ *
+ * @param handle
+ * @param component The pointer to the component.
+ * @return Alignment of the component.
+ */
+PGM_API size_t PGM_meta_component_alignment(PGM_Handle* handle, PGM_MetaComponent const* component);
+
+/**
+ * @brief Get number of attributes of the component.
+ *
+ * @param handle
+ * @param component The pointer to the component.
+ * @return Number of attributes.
+ */
+PGM_API PGM_Idx PGM_meta_n_attributes(PGM_Handle* handle, PGM_MetaComponent const* component);
+
+/**
+ * @brief Get pointer of idx-th attribute of a component.
+ *
+ * @param handle
+ * @param component The pointer to the component.
+ * @param idx The sequence number, should be between [0, PGM_meta_n_attributes())
+ * @return The pointer to the idx-th attribute. The pointer is permanantly valid.
+ * Or a NULL if your input is out of bound.
+ */
+PGM_API PGM_MetaAttribute const* PGM_meta_get_attribute_by_idx(PGM_Handle* handle, PGM_MetaComponent const* component,
+                                                               PGM_Idx idx);
+/**
+ * @brief Get pointer of a attribute by name.
+ *
+ * @param handle
+ * @param dataset The name of the dataset.
+ * @param component The name of the component.
+ * @param attribute The name of the attribute.
+ * @return The pointer to the component with that name. The pointer is permanantly valid.
+ * Or a NULL if your input is out of bound.
+ */
+PGM_API PGM_MetaAttribute const* PGM_meta_get_attribute_by_name(PGM_Handle* handle, char const* dataset,
+                                                                char const* component, char const* attribute);
+
+/**
+ * @brief Get attribute name.
+ *
+ * @param handle
+ * @param attribute The pointer to attribute.
+ * @return The name of the attribute in char const*. The pointer is permanantly valid.
+ */
+PGM_API char const* PGM_meta_attribute_name(PGM_Handle* handle, PGM_MetaAttribute const* attribute);
+
+/**
+ * @brief Get the type of an attribute.
+ *
+ * @param handle
+ * @param attribute The pointer to attribute.
+ * @return The type of the attribute as in enum PGM_CType.
+ *
+ */
+PGM_API PGM_Idx PGM_meta_attribute_ctype(PGM_Handle* handle, PGM_MetaAttribute const* attribute);
+
+/**
+ * @brief Get the offset of an attribute in a component.
+ *
+ * @param handle
+ * @param attribute The pointer to attribute.
+ * @return The offset of this attribute.
+ */
+PGM_API size_t PGM_meta_attribute_offset(PGM_Handle* handle, PGM_MetaAttribute const* attribute);
+
+/**
+ * @brief Get whether the system is little endian.
+ *
+ * @param handle
+ * @return 1 if the system is litten endian; 0 if the system is big endian.
+ */
+PGM_API int PGM_is_little_endian(PGM_Handle* handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

power_grid_model/_core/power_grid_model_c/include/power_grid_model_c/model.h

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+//
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @brief header file which includes model functions
+ *
+ */
+
+#pragma once
+#ifndef POWER_GRID_MODEL_C_MODEL_H
+#define POWER_GRID_MODEL_C_MODEL_H
+
+#include "basics.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Create a new instance of Power Grid Model.
+ *
+ * This is the main function to create a new model.
+ * You need to prepare the buffer data for input.
+ * The returned model need to be freed by PGM_destroy_model()
+ *
+ * @param handle
+ * @param system_frequency The frequency of the system, usually 50 or 60 Hz
+ * @param input_dataset Pointer to an instance of PGM_ConstDataset. It should have data type "input".
+ * @return The opaque pointer to the created model.
+ * If there are errors during the creation, a NULL is returned.
+ * Use PGM_error_code() and PGM_error_message() to check the error.
+ */
+PGM_API PGM_PowerGridModel* PGM_create_model(PGM_Handle* handle, double system_frequency,
+                                             PGM_ConstDataset const* input_dataset);
+
+/**
+ * @brief Update the model by changing mutable attributes of some elements.
+ *
+ * Use PGM_error_code() and PGM_error_message() to check if there are errors in the update.
+ * NOTE: The model will be in an undefined state after errors occured during the update and should be destroyed.
+ *
+ * @param handle
+ * @param model A pointer to an existing model.
+ * @param update_dataset Pointer to an instance of PGM_ConstDataset. It should have data type "update".
+ * @return
+ */
+PGM_API void PGM_update_model(PGM_Handle* handle, PGM_PowerGridModel* model, PGM_ConstDataset const* update_dataset);
+
+/**
+ * @brief Make a copy of an existing model.
+ *
+ * The returned model need to be freed by PGM_destroy_model()
+ *
+ * @param handle
+ * @param model A pointer to an existing model
+ * @return A opaque pointer to the new copy.
+ * If there are errors during the creation, a NULL is returned.
+ * Use PGM_error_code() and PGM_error_message() to check the error.
+ */
+PGM_API PGM_PowerGridModel* PGM_copy_model(PGM_Handle* handle, PGM_PowerGridModel const* model);
+
+/**
+ * @brief Get the sequence numbers based on list of ids in a given component.
+ *
+ * For example, if there are 5 nodes in the model with id [10, 2, 5, 15, 30].
+ * We have a node ID list of [2, 5, 15, 5, 10, 10, 30].
+ * We would like to know the sequence number of each element in the model.
+ * Calling this function should result in a sequence array of [1, 2, 3, 2, 0, 0, 4].
+ *
+ * If you supply a non-existing ID in the ID array, an error will be raised.
+ * Use PGM_error_code() and PGM_error_message() to check the error.
+ *
+ * @param handle
+ * @param model A pointer to an existing model.
+ * @param component A char const* string as component name.
+ * @param size The size of the ID array.
+ * @param ids A pointer to a #PGM_ID array buffer, this should be at least length of size.
+ * @param indexer A pointer to a #PGM_Idx array buffer. The results will be written to this array.
+ * The array should be pre-allocated with at least length of size.
+ */
+PGM_API void PGM_get_indexer(PGM_Handle* handle, PGM_PowerGridModel const* model, char const* component, PGM_Idx size,
+                             PGM_ID const* ids, PGM_Idx* indexer);
+
+/**
+ * @brief Execute a one-time or batch calculation.
+ *
+ * This is the main function to execute calculation.
+ * You can choose to execute one-time calculation or batch calculation,
+ * by controlling the batch_dataset argument.
+ * If batch_dataset == NULL, it is a one-time calculation.
+ * If batch_dataset != NULL, it is a batch calculation with batch update in the batch_dataset.
+ *
+ * The user can use the function set_next_cartesian_product_dimension() to combine multiple batch datasets
+ * to create a multi-dimension batch calculation using a linked list pattern. The calculation core will
+ * interpret the combined dataset as a cartesian product on a linked list of all the scenarios.
+ * Each batch dataset in the linked list represents one dimension of the cartesian product.
+ *
+ * You need to pre-allocate all output buffer.
+ *
+ * Use PGM_error_code() and PGM_error_message() to check the error.
+ *
+ * @param handle
+ * @param model A pointer to an existing model.
+ * @param opt A pointer to options, you need to pre-set all the calculation options you want.
+ * @param output_dataset A pointer to an instance of PGM_MutableDataset.
+ *   The dataset should have type "*_output", depending on the type of dataset.
+ *   You need to pre-allocate all output memory buffers.
+ *   You do not need to output all the component types as in the input.
+ *   For example, you can choose only create output buffers for node, not for line.
+ * @param batch_dataset A pointer to an instance of PGM_ConstDataset for batch calculation.
+ *   Or NULL for single calculation.
+ *   The dataset should have is_batch == true. The type of the dataset should be "update".
+ * @return
+ */
+PGM_API void PGM_calculate(PGM_Handle* handle, PGM_PowerGridModel* model, PGM_Options const* opt,
+                           PGM_MutableDataset const* output_dataset, PGM_ConstDataset const* batch_dataset);
+
+/**
+ * @brief Destroy the model returned by PGM_create_model() or PGM_copy_model().
+ *
+ * @param model The pointer to the model.
+ */
+PGM_API void PGM_destroy_model(PGM_PowerGridModel* model);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

power_grid_model/_core/power_grid_model_c/include/power_grid_model_c/options.h

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+//
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @brief header file which includes options functions
+ *
+ */
+
+#pragma once
+#ifndef POWER_GRID_MODEL_C_OPTIONS_H
+#define POWER_GRID_MODEL_C_OPTIONS_H
+
+#include "basics.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Create an option instance.
+ *
+ * The option is needed to run calculations.
+ * This function create a new option instance with the following default values:
+ *   - calculation_type: PGM_power_flow
+ *   - calculation_method: PGM_default_method
+ *   - symmetric: 1
+ *   - err_tol: 1e-8
+ *   - max_iter: 20
+ *   - threading: -1
+ *   - short_circuit_voltage_scaling: PGM_short_circuit_voltage_scaling_maximum
+ *   - experimental_features: PGM_experimental_features_disabled
+ *
+ * @param handle
+ * @return The pointer to the option instance. Should be freed by PGM_destroy_options().
+ */
+PGM_API PGM_Options* PGM_create_options(PGM_Handle* handle);
+
+/**
+ * @brief Free an option instance.
+ *
+ * @param opt The pointer to the option instance created by PGM_create_options().
+ */
+PGM_API void PGM_destroy_options(PGM_Options* opt);
+
+/**
+ * @brief Specify type of calculation.
+ *
+ * @param handle
+ * @param opt The pointer to the option instance.
+ * @param type See #PGM_CalculationType .
+ */
+PGM_API void PGM_set_calculation_type(PGM_Handle* handle, PGM_Options* opt, PGM_Idx type);
+
+/**
+ * @brief Specify method of calculation.
+ *
+ * @param handle
+ * @param opt The pointer to the option instance.
+ * @param method See #PGM_CalculationMethod .
+ */
+PGM_API void PGM_set_calculation_method(PGM_Handle* handle, PGM_Options* opt, PGM_Idx method);
+
+/**
+ * @brief Specify if we are calculating symmetrically or asymmetrically.
+ *
+ * @param handle
+ * @param opt The pointer to the option instance.
+ * @param sym See #PGM_CalculationSymmetry . 1 for symmetric calculation; 0 for asymmetric calculation.
+ */
+PGM_API void PGM_set_symmetric(PGM_Handle* handle, PGM_Options* opt, PGM_Idx sym);
+
+/**
+ * @brief Specify the error tolerance to stop iterations. Only applicable if using iterative method.
+ *
+ * It is in terms of voltage deviation per iteration in p.u.
+ *
+ * @param handle
+ * @param opt The pointer to the option instance.
+ * @param err_tol The relative votlage deviation tolerance.
+ */
+PGM_API void PGM_set_err_tol(PGM_Handle* handle, PGM_Options* opt, double err_tol);
+
+/**
+ * @brief Specify maximum number of iterations. Only applicable if using iterative method.
+ *
+ * @param handle
+ * @param opt The pointer to the option instance.
+ * @param max_iter The maximum number of iterations.
+ */
+PGM_API void PGM_set_max_iter(PGM_Handle* handle, PGM_Options* opt, PGM_Idx max_iter);
+
+/**
+ * @brief Specify the multi-threading strategy. Only applicable for batch calculation.
+ *
+ * @param handle
+ * @param opt The pointer to the option instance.
+ * @param threading The value of the threading setting. See below:
+ *   - -1: No multi-threading, calculate sequentially.
+ *   - 0: use number of machine available threads.
+ *   - >0: specify number of threads you want to calculate in parallel.
+ */
+PGM_API void PGM_set_threading(PGM_Handle* handle, PGM_Options* opt, PGM_Idx threading);
+
+/**
+ * @brief Specify the voltage scaling min/max for short circuit calculations
+ *
+ * @param handle
+ * @param opt pointer to option instance
+ * @param short_circuit_voltage_scaling See #PGM_ShortCircuitVoltageScaling
+ */
+PGM_API void PGM_set_short_circuit_voltage_scaling(PGM_Handle* handle, PGM_Options* opt,
+                                                   PGM_Idx short_circuit_voltage_scaling);
+
+/**
+ * @brief Specify the tap changing strategy for power flow calculations
+ *
+ * @param handle
+ * @param opt pointer to option instance
+ * @param tap_changing_strategy See #PGM_TapChangingStrategy
+ */
+PGM_API void PGM_set_tap_changing_strategy(PGM_Handle* handle, PGM_Options* opt, PGM_Idx tap_changing_strategy);
+
+/**
+ * @brief Enable/disable experimental features.
+ *
+ * [Danger mode]
+ *
+ * The behavior of experimental features may not be final and no stability guarantees are made to the users.
+ * Features marked as 'experimental' as well as the behavior of experimental functionality itself may change over time.
+ *
+ * @param handle
+ * @param opt pointer to option instance
+ * @param experimental_features See #PGM_ExperimentalFeatures
+ */
+PGM_API void PGM_set_experimental_features(PGM_Handle* handle, PGM_Options* opt, PGM_Idx experimental_features);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

power_grid_model/_core/power_grid_model_c/include/power_grid_model_c/serialization.h

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+//
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @brief header file which includes serialization functions
+ *
+ */
+
+#pragma once
+#ifndef POWER_GRID_MODEL_C_SERIALIZATION_H
+#define POWER_GRID_MODEL_C_SERIALIZATION_H
+
+#include "basics.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Create a deserializer from binary buffer/byte stream.
+ * @param handle
+ * @param data The pointer to the byte stream.
+ * @param size The size of the byte stream.
+ * @param serialization_format The desired data format of the serialization. See #PGM_SerializationFormat .
+ * @return A pointer to the deserializer instance. Should be freed by PGM_destroy_deserializer().
+ *     Returns NULL if errors occured (check the handle for error information).
+ */
+PGM_API PGM_Deserializer* PGM_create_deserializer_from_binary_buffer(PGM_Handle* handle, char const* data, PGM_Idx size,
+                                                                     PGM_Idx serialization_format);
+
+/**
+ * @brief Create a deserializer from a null terminated C string.
+ * @param handle
+ * @param data_string The pointer to the null-terminated C string.
+ * @param serialization_format The desired data format of the serialization. See #PGM_SerializationFormat .
+ * @return A pointer to the deserializer instance. Should be freed by PGM_destroy_deserializer().
+ *     Returns NULL if errors occured (check the handle for error information).
+ */
+PGM_API PGM_Deserializer* PGM_create_deserializer_from_null_terminated_string(PGM_Handle* handle,
+                                                                              char const* data_string,
+                                                                              PGM_Idx serialization_format);
+
+/**
+ * @brief Get the PGM_WritableDataset object from the deserializer.
+ * @param handle
+ * @param deserializer The pointer to the deserializer.
+ * @return A pointer the instance of PGM_WritableDataset.
+ *     The pointer has the same lifetime as the deserializer.
+ *     Use PGM_writable_dataset_get_info() to get the information of the dataset.
+ *     Use PGM_writable_dataset_set_buffer() to set buffer.
+ */
+PGM_API PGM_WritableDataset* PGM_deserializer_get_dataset(PGM_Handle* handle, PGM_Deserializer* deserializer);
+
+/**
+ * @brief Parse the dataset and write to the user-provided buffers.
+ *     The buffers must be set through PGM_writable_dataset_set_buffer().
+ * @param handle
+ * @param deserializer The pointer to the deserializer
+ * @return No return value; check handle for error.
+ */
+PGM_API void PGM_deserializer_parse_to_buffer(PGM_Handle* handle, PGM_Deserializer* deserializer);
+
+/**
+ * @brief Destory deserializer
+ * @param deserializer pointer to deserializer
+ * @return
+ */
+PGM_API void PGM_destroy_deserializer(PGM_Deserializer* deserializer);
+
+/**
+ * @brief Create a serializer object based on input dataset, the buffers must be set in advance.
+ * @param handle
+ * @param dataset A pointer to an instance of PGM_ConstDataset
+ * @param serialization_format The desired data format of the serialization. See #PGM_SerializationFormat .
+ * @return A pointer to the new serializer object. Should be freed by PGM_destroy_serializer()
+ *     Returns NULL if errors occured (check the handle for error information).
+ */
+PGM_API PGM_Serializer* PGM_create_serializer(PGM_Handle* handle, PGM_ConstDataset const* dataset,
+                                              PGM_Idx serialization_format);
+
+/**
+ * @brief Serialize the dataset into a binary buffer format.
+ * @param handle
+ * @param serializer A pointer to an existing serializer.
+ * @param use_compact_list 1 for use compact list per element of serialization; 0 for use dictionary per element.
+ * @param data Output argument: the data pointer of the packed buffer will be written to *data.
+ * @param size Output argument: the length of the packed buffer will be written to *size.
+ * @return No return value; check handle for error.
+ */
+PGM_API void PGM_serializer_get_to_binary_buffer(PGM_Handle* handle, PGM_Serializer* serializer,
+                                                 PGM_Idx use_compact_list, char const** data, PGM_Idx* size);
+
+/**
+ * @brief Serialize the dataset into a zero terminated C string.
+ *     Only supported for uncompressed data formats.
+ * @param handle
+ * @param serializer A pointer to an existing serializer.
+ * @param use_compact_list 1 for use compact list per element of serialization; 0 for use dictionary per element.
+ * @param indent The indentation of the JSON, use -1 for no indent and no new line (compact format).
+ * @return A NULL-terminated json string.
+ *     Returns NULL if errors occured (check the handle for error information).
+ */
+PGM_API char const* PGM_serializer_get_to_zero_terminated_string(PGM_Handle* handle, PGM_Serializer* serializer,
+                                                                 PGM_Idx use_compact_list, PGM_Idx indent);
+
+/**
+ * @brief Destroy serializer.
+ * @param serializer The pointer to the serializer.
+ * @return
+ */
+PGM_API void PGM_destroy_serializer(PGM_Serializer* serializer);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif