Skip to content

[FEATURE] Migrate experimental features to PGM_Handle instead of PGM_Options #934

Description

@mgovers

The current C API exposes experimental features as part of the PGM_Options interface (https://power-grid-model.readthedocs.io/en/stable/api_reference/power-grid-model-c-api-reference.html#_CPPv429PGM_set_experimental_featuresP10PGM_HandleP11PGM_Options7PGM_Idx).

This feature instead sets the experimental feature to be part of the handle instead of the options.

Breaking changes to C API (at a major version bump)

  • To the PGM_Handle, add the experimental_features member field
  • Update the PGM_set_experimental_features function to remove the PGM_Options* opt from it and move it to the handle header + implemenation.
  • In the implementation of PGM_set_experimental_features, set the experimental_features member field of the PGM_Handle
  • Update the C++ API to be able to handle this. Currently, it uses a separate handle for the options, which may result in issues.
  • Update the tests to be able to handle this. Currently, it uses the PGM_Options for this.
  • Update the PGM_set_experimental_features function to remove the PGM_Options* opt from it.

NOTE: changing the function signature is not only an API but also an ABI breaking change. This is known and accepted after considering the following reasons:

  1. The PGM_set_experimental_features already is marked both [DANGER MODE] and documented Features marked as 'experimental' as well as the behavior of experimental functionality itself may change over time.
  2. There is a major version bump. It is listed as breaking and documented as such in the release notes and the announcement.

Activity

  1. added theissue type on Mar 25, 2025
  2. mgovers commented on Jun 11, 2026

    @mgovers
    MemberAuthor

    Since we are once again encountering the necessity for this (see also #1334), should we revisit the decision to not plan this?

    Some points for the rationale:

    1. it's experimental... it may change... there's no backwards compatibility issues as long as PGM_set_experimental_features(handle, options, disabled) results in the same behavior. It's a non-issue.
    2. we're looking to do a major version bump. Now is the time.
    3. the Python library now uses a thread-local handle, rather than one handle for all threads. Parallel testing is no longer an issue. We just need to disable experimental features after a single thread test is done. Some pattern like with experimental_features_enabled(): ... could do the trick
    4. the whole C++ library is officially experimental (although we know of a user that uses this) so we can change the behavior if we need to. The main issue here is how to set experimental features on an object. A potential resolution could be to optionally provide a C++ constructor overload that takes an external handle instead of one that is created internally in the object.

    Any objections to re-opening this?

    #772 (comment)

  3. added this to the Release 2.0 milestone on Jun 11, 2026
  4. moved this from Q3 2026 to Q4 2026 in Power Grid Modelon Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew feature or request

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions