power_grid_model_c
Defines
-
POWER_GRID_MODEL_C_H
Typedefs
-
typedef int64_t PGM_Idx
-
typedef int32_t PGM_ID
-
typedef struct PGM_PowerGridModel PGM_PowerGridModel
Opaque struct for the PowerGridModel class.
-
typedef struct PGM_Handle PGM_Handle
Opaque struct for the handle class.
The handle class is used to store error and information
-
typedef struct PGM_Options PGM_Options
Opaque struct for the option class.
The option class is used to set calculation options like calculation method.
Enums
-
enum PGM_CalculationType
Enumeration for calculation type.
Values:
-
enumerator PGM_power_flow
power flow calculation
-
enumerator PGM_state_estimation
state estimation calculation
-
enumerator PGM_short_circuit
short circuit calculation
-
enumerator PGM_power_flow
-
enum PGM_CalculationMethod
Enumeration for calculation method.
Values:
-
enumerator PGM_default_method
the default method for each calculation type, e.g. Newton-Raphson for power flow
-
enumerator PGM_linear
linear constant impedance method for power flow
-
enumerator PGM_newton_raphson
Newton-Raphson method for power flow
-
enumerator PGM_iterative_linear
iterative linear method for state estimation
-
enumerator PGM_iterative_current
linear current method for power flow
-
enumerator PGM_linear_current
iterative constant impedance method for power flow
-
enumerator PGM_iec60909
fault analysis for short circuits using the iec60909 standard
-
enumerator PGM_default_method
Functions
-
PGM_Handle *PGM_create_handle(void)
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()
- Returns:
Pointer to the created handle
-
void PGM_destroy_handle(PGM_Handle *handle)
Destroy the handle.
- Parameters:
handle – Pointer to the handle created by PGM_create_handle()
-
PGM_Idx PGM_error_code(PGM_Handle const *handle)
Get error code of last operation.
- Parameters:
handle – Pointer to the handle you just used for an operation
- Returns:
The error code, see PGM_ErrorCode
-
char const *PGM_error_message(PGM_Handle const *handle)
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.
- Parameters:
handle – Pointer to the handle you just used for an operation
- Returns:
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_Idx PGM_n_failed_scenarios(PGM_Handle const *handle)
Get the number of failed scenarios, only applicable when you just execute a batch calculation.
- Parameters:
handle – Pointer to the handle you just used for a batch calculation
- Returns:
The number of failed scenarios
-
PGM_Idx const *PGM_failed_scenarios(PGM_Handle const *handle)
Get the list of failed scenarios, only applicable when you just execute a batch calculation.
- Parameters:
handle – Pointer to the handle you just used for a batch calculation
- Returns:
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.
-
char const **PGM_batch_errors(PGM_Handle const *handle)
Get the list of batch errors, only applicable when you just execute a batch calculation.
- Parameters:
handle – Pointer to the handle you just used for a batch calculation
- Returns:
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.
-
void PGM_clear_error(PGM_Handle *handle)
Clear and reset the handle.
- Parameters:
handle – Pointer to the handle
-
PGM_Idx PGM_meta_n_datasets(PGM_Handle *handle)
Get number of datasets.
- Parameters:
handle –
- Returns:
The number of datasets
-
char const *PGM_meta_dataset_name(PGM_Handle *handle, PGM_Idx idx)
Get name of idx-th dataset.
- Parameters:
handle –
idx – the sequence number, should be between [0, PGM_meta_n_datasets())
- Returns:
The name of idx-th dataset in a char const*. The pointer is permanantly valid. Or a NULL if your input is out of bound.
-
PGM_Idx PGM_meta_n_components(PGM_Handle *handle, char const *dataset)
Get the number of components for a dataset.
You will get one of the following depending on the idx
input
update
sym_output
asym_output
sc_output
- Parameters:
handle –
dataset – name of dataset
- Returns:
Number of components, or zero if your input is invalid
-
char const *PGM_meta_component_name(PGM_Handle *handle, char const *dataset, PGM_Idx idx)
Get name of idx-th component.
- Parameters:
handle –
dataset – name of dataset
idx – sequence number of component, should be between [0, PGM_meta_n_components())
- Returns:
The name of idx-th component in a char const*. The pointer is permanantly valid. Or a NULL if your input is out of bound.
-
size_t PGM_meta_component_size(PGM_Handle *handle, char const *dataset, char const *component)
Get size of the component.
- Parameters:
handle –
dataset – dataset name
component – component name
- Returns:
Size of the component. Or zero if your input is invalid.
-
size_t PGM_meta_component_alignment(PGM_Handle *handle, char const *dataset, char const *component)
Get alignment of the component.
- Parameters:
handle –
dataset – dataset name
component – component name
- Returns:
Alignment of the component. Or zero if your input is invalid.
-
PGM_Idx PGM_meta_n_attributes(PGM_Handle *handle, char const *dataset, char const *component)
Get number of attributes of the component.
- Parameters:
handle –
dataset – dataset name
component – component name
- Returns:
Number of attributes. Or zero if your input is invalid.
-
char const *PGM_meta_attribute_name(PGM_Handle *handle, char const *dataset, char const *component, PGM_Idx idx)
Get idx-th of attribute name.
- Parameters:
handle –
dataset – dataset name
component – component name
idx – sequence number of attribute, should be between [0, PGM_meta_n_attributes())
- Returns:
Name of the attribute in char const*. The pointer is permanantly valid. Or NULL if your input is invalid.
-
char const *PGM_meta_attribute_ctype(PGM_Handle *handle, char const *dataset, char const *component, char const *attribute)
Get the type of an attribute.
Valid types are:
int32_t
int8_t
double
double[3]
- Parameters:
handle –
dataset – dataset name
component – component name
attribute – attribute name
- Returns:
Type of the attribute in char const*. The string is a valid C type name. The pointer is permanantly valid. Or NULL if your input is invalid.
-
size_t PGM_meta_attribute_offset(PGM_Handle *handle, char const *dataset, char const *component, char const *attribute)
Get the ofsset of an attribute in a component.
- Parameters:
handle –
dataset – dataset name
component – component name
attribute – attribute name
- Returns:
Offset of this attribute. Or zero if your input is invalid.
-
int PGM_is_little_endian(PGM_Handle *handle)
Get if the system is little endian.
- Parameters:
handle –
- Returns:
One if the system is litten endian. Zero if the system is big endian.
-
void *PGM_create_buffer(PGM_Handle *handle, char const *dataset, char const *component, PGM_Idx size)
Create a buffer with certain size and component type.
You can use this function to allocate a buffer. You can also use your own allocation function to do that with size and alignment got from PGM_meta_component_size() and PGM_meta_component_alignment(). The buffer created by this function should be freed by PGM_destroy_buffer().
It is recommended to call PGM_buffer_set_nan() after you create an input or update buffer. In this way all the attributes will be set to NaN. And if there is a new optional attribute added in the future. You have garantee that your code is still compatible because that optional attribute will be set to NaN and the default value will be used.
- Parameters:
handle –
dataset – dataset name
component – component name
size – size of the buffer in terms of number of elements
- Returns:
Pointer to the buffer. Or NULL if your input is invalid.
-
void PGM_destroy_buffer(void *ptr)
Destroy the buffer you created using PGM_create_buffer().
NOTE: do not call this function on the buffer you created by your own function.
- Parameters:
ptr – Pointer to the buffer created using PGM_create_buffer()
-
void PGM_buffer_set_nan(PGM_Handle *handle, char const *dataset, char const *component, void *ptr, PGM_Idx size)
Set all the attributes of a buffer to NaN.
- Parameters:
handle –
dataset – dataset name
component – component name
ptr – pointer to buffer, created either by PGM_create_buffer() or your own function.
size – size of the buffer in terms of number of elements
-
void PGM_buffer_set_value(PGM_Handle *handle, char const *dataset, char const *component, char const *attribute, void *buffer_ptr, void const *src_ptr, PGM_Idx size, PGM_Idx src_stride)
Set value of a certain attribute from an array to the component buffer.
You can use this function to set value. You can also set value by proper pointer arithmetric and casting, using the offset information returned by PGM_meta_attribute_offset(). If your input is invalid, the handle will contain the error message.
- Parameters:
handle –
dataset – dataset name
component – component name
attribute – attribute name
buffer_ptr – pointer to the buffer
src_ptr – pointer to the source array you want to retrieve the value from
size – size of the buffer in terms of number of elements
src_stride – stride of the source array in bytes. You can set it to -1, the default stride of the size of the attribute type (like sizeof(double)). If you set it to a positive number, the i-th set-value will retrieve the source data at (void const*)((char const*)src_ptr + i * src_stride)
-
void PGM_buffer_get_value(PGM_Handle *handle, char const *dataset, char const *component, char const *attribute, void const *buffer_ptr, void *dest_ptr, PGM_Idx size, PGM_Idx dest_stride)
Get value of a certain attribute from the component buffer to an array.
You can use this function to get value. You can also get value by proper pointer arithmetric and casting, using the offset information returned by PGM_meta_attribute_offset(). If your input is invalid, the handle will contain the error message.
- Parameters:
handle –
dataset – dataset name
component – component name
attribute – attribute name
buffer_ptr – pointer to the buffer
dest_ptr – pointer to the destination array you want to save the value to
size – size of the buffer in terms of number of elements
dest_stride – stride of the destination array in bytes. You can set it to -1, the default stride of the size of the attribute type (like sizeof(double)). If you set it to a positive number, the i-th get-value will retrieve the source data at (void*)((char*)dest_ptr + i * dest_stride)
-
PGM_Options *PGM_create_options(PGM_Handle *handle)
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
- Parameters:
handle –
- Returns:
a pointer to the option instance. Should be freed by PGM_destroy_options()
-
void PGM_destroy_options(PGM_Options *opt)
Free the option instance.
- Parameters:
opt – pointer to an option instance created by PGM_create_options()
-
void PGM_set_calculation_type(PGM_Handle *handle, PGM_Options *opt, PGM_Idx type)
Specify type of calculation.
- Parameters:
handle –
opt – pointer to option instance
type – See PGM_CalculationType
-
void PGM_set_calculation_method(PGM_Handle *handle, PGM_Options *opt, PGM_Idx method)
Specify method of calculation.
- Parameters:
handle –
opt – pointer to option instance
method – See PGM_CalculationMethod
-
void PGM_set_symmetric(PGM_Handle *handle, PGM_Options *opt, PGM_Idx sym)
Specify if we are calculating symmetrically or asymmetrically.
- Parameters:
handle –
opt – pointer to option instance
sym – One for symmetric calculation. Zero for asymmetric calculation
-
void PGM_set_err_tol(PGM_Handle *handle, PGM_Options *opt, double err_tol)
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.
- Parameters:
handle –
opt – pointer to option instance
err_tol – Relative votlage deviation tolerance
-
void PGM_set_max_iter(PGM_Handle *handle, PGM_Options *opt, PGM_Idx max_iter)
Specify maximum number of iterations. Only applicable if using iterative method.
- Parameters:
handle –
opt – pointer to option instance
max_iter – Maximum number of iterations
-
void PGM_set_threading(PGM_Handle *handle, PGM_Options *opt, PGM_Idx threading)
Specify the multi-threading strategy. Only applicable for batch calculation.
- Parameters:
handle –
opt – pointer to option instance
threading – Threading option. 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_PowerGridModel *PGM_create_model(PGM_Handle *handle, double system_frequency, PGM_Idx n_components, char const **components, PGM_Idx const *component_sizes, void const **input_data)
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()
- Parameters:
handle –
system_frequency – frequency of the system, usually 50 or 60 Hz
n_components – number of component types in the input data
components – Pointer to a char const* array consisting the name of each component. For i-th component, components[i] should be a char const* string of the component name
component_sizes – Pointer to an integer array specifying the size of each component. For i-th component, component_sizes[i] specifies how many elements there are for this component.
input_data – Pointer to a void const* array consisting the input data buffers. For i-th component, input_data[i] is a void const* pointer to the data buffer for this component.
- Returns:
A 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.
-
void PGM_update_model(PGM_Handle *handle, PGM_PowerGridModel *model, PGM_Idx n_components, char const **components, PGM_Idx const *component_sizes, void const **update_data)
Update the model by changing mutable attributes of some elements.
All the elements you supply in the update dataset should have valid ids which exist in the original model.
Use PGM_error_code() and PGM_error_message() to check if there are errors in the update.
- Parameters:
handle –
model – Pointer to the existing model
n_components – number of component types you want to update
components – Pointer to a char const* array consisting the name of each component. For i-th component, components[i] should be a char const* string of the component name
component_sizes – Pointer to an integer array specifying the size of each component. For i-th component, component_sizes[i] specifies how many elements you want to update for this component. NOTE: You do not need to update all the elemenmts for this component.
update_data – Pointer to a void const* array consisting the update data buffers. For i-th component, update_data[i] is a void const* pointer to the update data buffer for this component.
-
PGM_PowerGridModel *PGM_copy_model(PGM_Handle *handle, PGM_PowerGridModel const *model)
Make a copy of an existing model.
The returned model need to be freed by PGM_destroy_model()
- Parameters:
handle –
model – Pointer to an existing model
- Returns:
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.
-
void PGM_get_indexer(PGM_Handle *handle, PGM_PowerGridModel const *model, char const *component, PGM_Idx size, PGM_ID const *ids, PGM_Idx *indexer)
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.
- Parameters:
handle –
model – Pointer to model
component – A char const* string as component name
size – Size of the ID array
ids – Pointer to PGM_ID array buffer, this should be at least length of size.
indexer – 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.
-
void PGM_calculate(PGM_Handle *handle, PGM_PowerGridModel *model, PGM_Options const *opt, PGM_Idx n_output_components, char const **output_components, void **output_data, PGM_Idx n_scenarios, PGM_Idx n_update_components, char const **update_components, PGM_Idx const *n_component_elements_per_scenario, PGM_Idx const **indptrs_per_component, void const **update_data)
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 n_update_components argument. If n_update_components == 0, it is a one-time calculation. n_scenario will be ignored and assumed to be 1. If n_update_components > 0, it is a batch calculation.
You need to pre-allocate all output buffer.
Use PGM_error_code() and PGM_error_message() to check the error.
- Parameters:
handle –
model – Pointer to model
opt – Pointer to options, you need to pre-set all the calculation options you want
n_output_components – Number of components you want in the output. Note you do not need to get all the components as in the input in the output. You can select only certain component (like, node, line) in the output.
output_components – Pointer to a char const* array consisting the name of each output component. For i-th component, output_components[i] should be a char const* string of the output component name
output_data – Pointer to a void* array consisting the output data buffers. For i-th component, output_data[i] is a void* pointer to the output data buffer for this component. NOTE: Once you decide to select one component to be in the output. You always get all the elements for this component. This means the output data buffer should be at least the size of n_scenarios * n_element_for_this_component_in_the_model. Otherwise you get buffer overflow! This is also the reason you do not specify the number of elements per component in output buffer.
n_scenarios – Number of scenarios in a batch calculation. Note this argument is ignored if you set n_update_components = 0. Then the n_scenarios is always 1.
n_update_components – Number of components you want to update in a batch calculation. If you set n_update_components = 0, it means it is a one-time calculation instead of batch calculation.
update_components – Pointer to a char const* array consisting the name of each update component. For i-th component, update_components[i] should be a char const* string of the update component name.
n_component_elements_per_scenario – Pointer to an integer array specifying number of elements to be updated per component per scenario. For i-th component, n_component_elements_per_scenario[i] specifies how many elements you want to update for this component per scenario. If you want to update different number of elements per scenario for i-th component, you can set n_component_elements_per_scenario[i] = -1. In this case the program will look at indptrs_per_component[i].
indptrs_per_component – Pointer to an integer pointer array specifying different number of updated elements per scenario per component. For i-th component, if n_component_elements_per_scenario[i] == -1, indptrs_per_component[i] should be a pointer to a PGM_Idx
array with at least length of n_scenarios + 1. For j-th scenario, the number of updated elements for i-th components is specified by indptrs_per_component[i][j + 1] - indptrs_per_component[i][j].
If n_component_elements_per_scenario[i] > 0, indptrs_per_component[i] should be a NULL. If all entries in n_component_elements_per_scenario are larger than zero, indptrs_per_component can be a NULL as a whole.
update_data –
Pointer to a void const* array consisting the update data buffers for batch calculation. For i-th component, update_data[i] is a void const* pointer to the update data buffer for this component.
If n_component_elements_per_scenario[i] > 0, the begin and end (excluding) pointer iterator for j-th scenario is
begin = (UpdateType const*)update_data[i] + j * n_component_elements_per_scenario[i]
end = (UpdateType const*)update_data[i] + (j + 1) * n_component_elements_per_scenario[i]
If n_component_elements_per_scenario[i] == -1, the begin and end (excluding) pointer iterator for j-th scenario is
begin = (UpdateType const*)update_data[i] + indptrs_per_component[i][j]
end = (UpdateType const*)update_data[i] + indptrs_per_component[i][j + 1]
-
void PGM_destroy_model(PGM_PowerGridModel *model)
Destroy the model returned by PGM_create_model() or PGM_copy_model()
- Parameters:
model – pointer to the model