Skip to content

Add market topology to the config model - #126

Open
cwasicki wants to merge 2 commits into
frequenz-floss:v0.x.xfrom
cwasicki:topology
Open

Add market topology to the config model#126
cwasicki wants to merge 2 commits into
frequenz-floss:v0.x.xfrom
cwasicki:topology

Conversation

@cwasicki

Copy link
Copy Markdown
Collaborator

Adds a data model for market topology under the assets config namespace, based on the Assets API MarketTopologyRelation, plus query helpers. The config extends the API model with plain relation-validity periods and delivery-area mappings on gridpool-free relations. It also makes the config package's implementation modules private.

Model

  • assets.relations: each record links at least two of a gridpool, microgrid and market location, filed under a G<>M<>L<> key derived from its own fields. Nothing is read from the key; check() verifies that the key and fields agree.
  • A gridpool relation carries its delivery_area. A gridpool-to-microgrid relation therefore carries one even without a market location. Gridpool-free microgrid-to-market-location relations may also carry one for direct mappings.
  • Delivery areas currently support only 16-character EIC codes. Their format and check character are validated, but not their registration with an EIC issuing office.
  • validity: each entry is a half-open [start, end) datetime period. A period may name a market use case (participation) for a gridpool relation, while a plain period describes relation validity without distinguishing a use case.
  • assets.market_locations: self-describing entries carrying their identifier, identifier scheme (MALO_ID by default), and Assets API market area (101, EU_DE, by default). Raw market-location IDs remain document-wide keys, so the same ID cannot occur in several market areas.

Time-varying enterprise ownership is outside this change; Metadata.enterprise_id remains a scalar field.

Read API

AssetsConfig answers the common lookups:

  • find_relations(...) returns relations matching all supplied sides, use case and instant.
  • find_delivery_areas(...), find_market_locations(...) and find_microgrids(...) return deduplicated projections filtered by the other dimensions.

load_assets_from_files layers several files into one document, merging raw TOML tables before loading so an override keeps fields it leaves unset.

Refactor

The config package's implementation modules are made private with leading underscores, matching _graph_generator; the public surface remains the package __init__. This is split into its own commit.

Breaking changes

  • Metadata.delivery_area is removed; delivery areas are read from topology relations.
  • For a microgrid with gridpool relations, Metadata.gid, if set, must be their sole gridpool ID. Omit it when the microgrid participates in several gridpools.
  • load_configs_from_files now layers files field by field. Values omitted by a later file remain and cannot be removed by omission.
  • Direct imports of frequenz.gridpool.config.microgrid, .load and .assets break; import public names from frequenz.gridpool.config.

See RELEASE_NOTES.md for the full upgrading notes.

Follow-ups

  • Key microgrids by int: AssetsConfig.microgrids and the load_configs* return types remain str-keyed while relations use integer IDs. Normalising these is a separate follow-up PR.
  • Standalone market locations: whether to expose assets.market_locations entries not referenced by any relation through a dedicated query remains open.

The public surface is the config package, re-exported through its
`__init__`; the implementation modules take a leading underscore to
match `_graph_generator`, starting with `microgrid` and `load`.

Signed-off-by: cwasicki <126617870+cwasicki@users.noreply.github.com>
Describe market topology under `assets.relations`, mirroring the Assets
API `MarketTopologyRelation`: each record links at least two of a
gridpool, a microgrid and a market location, filed under a `g<>m<>l<>`
key derived from its own sides. A gridpool relation carries its
`delivery_area`, and its validity lives in `validity`, each entry a
half-open `datetime` period, with a market use case telling a gridpool's
participations apart.

Market locations and delivery areas are self-describing entries under
`assets.market_locations` and `assets.delivery_areas`, each carrying its
own identifier and how to read it, checked against the key it is filed
under.

`AssetsConfig` answers the common lookups with `find_relations` and the
projections `find_delivery_areas`, `find_market_locations` and
`find_microgrids`. `load_assets_from_files` layers several files into one
document, merging the raw tables so an override keeps fields it leaves
unset.

Signed-off-by: cwasicki <126617870+cwasicki@users.noreply.github.com>
@cwasicki
cwasicki requested review from a team as code owners August 21, 2026 17:53
@cwasicki
cwasicki requested review from cyiallou and llucax and removed request for a team August 21, 2026 17:53
@github-actions github-actions Bot added part:docs Affects the documentation part:tests Affects the unit, integration and performance (benchmarks) tests part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) labels Aug 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

part:docs Affects the documentation part:tests Affects the unit, integration and performance (benchmarks) tests part:tooling Affects the development tooling (CI, deployment, dependency management, etc.)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant