# Frequenz Gridpool Library Release Notes

## Summary

<!-- Here goes a general summary of what this release is about -->

## Upgrading

- Requires `frequenz-microgrid-component-graph` 0.6, which stops clamping the consumer
  and producer formulas. `ComponentGraph.consumer_formula()` and
  `ComponentGraph.producer_formula()` can now return values previously pinned
  to zero: a negative consumer total, or a positive producer total.

## New Features

<!-- Here goes the main new features and examples or instructions on how to use them -->

## Bug Fixes

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

# Frequenz Gridpool Library Release Notes

## Summary

This release rounds out `gridpool-cli` for the `assets` config layout and adds
gridpool enterprise ownership to the config model. The CLI can now generate,
validate, patch, and query merged config files.

## Upgrading

- The legacy config layouts are no longer migrated on load: top-level microgrid
  IDs and `meta`-nested microgrid fields are gone. A file with no `assets` table
  now loads as empty and contributes nothing to a merge, rather than having its
  top-level keys read as microgrid IDs. This lets a mixed list of files (some
  carrying an `[app]` table for their own config, some an `assets` table) be
  passed to `AssetsConfig.load_from_files` / `load_configs`, which reads only the
  `assets`-bearing ones. Rebuild any legacy-layout files with `generate-config`.

- `generate-config` now writes the `assets.microgrids` layout and stamps
  `assets.version`, instead of the legacy layout. Regenerate configs to get the
  current format; generated files then load back without a migration.

- `generate-config --inplace` refuses legacy-layout files (top-level or
  `meta`-nested), which it would duplicate rather than edit. Rebuild those from
  scratch.

## New Features

- `gridpool-cli validate <files>` checks config files offline and exits
  non-zero on the first error, to gate config-repo CI. Each file must be valid
  on its own, so a record names its own key and required fields; the files are
  then checked merged, for the cross-record checks.

- `gridpool-cli` accepts `FREQUENZ_API_KEY` and `FREQUENZ_API_SECRET` as a
  fallback pair for `ASSETS_API_AUTH_KEY` and `ASSETS_API_SIGN_SECRET`.

- Gridpools are described under `assets.gridpools`, each entry naming the
  enterprise that owns the gridpool. `AssetsConfig.find_enterprise(gridpool_id)`
  returns the configured owner.
  `gridpool-cli find-enterprise <gridpool_id> <files>` prints it from the config.
  `AssetsConfig.check` enforces the one-enterprise-per-gridpool invariant: a
  gridpool's microgrids may not disagree on it, and a declared enterprise must
  match the inferred one.

- A config derived from the Assets API now carries each microgrid's
  `enterprise_id`.

- `generate-config --inplace` refreshes managed values while preserving
  formatting; `--fill-missing` only adds absent values. Generated patches are
  validated before writing.

## Bug Fixes

- Config files with validity periods now load under marshmallow 3, not only
  marshmallow 4. `tomllib` yields native `datetime` objects, which marshmallow
  3's `DateTime` field rejected. `marshmallow` is now a direct dependency so the
  minimum-version test exercises this path.

# Frequenz Gridpool Library Release Notes

## Summary

This release rounds out `gridpool-cli` for the `assets` config layout and adds
gridpool enterprise ownership to the config model. The CLI can now generate,
validate, patch, and query merged config files.

## Upgrading

- `generate-config` now writes the `assets.microgrids` layout and stamps
  `assets.version`, instead of the legacy layout. Regenerate configs to get the
  current format; generated files then load back without a migration.

- `generate-config --inplace` refuses legacy-layout files (top-level or
  `meta`-nested), which it would duplicate rather than edit. Rebuild those from
  scratch.

## New Features

- `gridpool-cli validate <files>` checks config files offline and exits
  non-zero on the first error, to gate config-repo CI. Each file must be valid
  on its own, so a record names its own key and required fields; the files are
  then checked merged, for the cross-record checks.

- `gridpool-cli` accepts `FREQUENZ_API_KEY` and `FREQUENZ_API_SECRET` as a
  fallback pair for `ASSETS_API_AUTH_KEY` and `ASSETS_API_SIGN_SECRET`.

- Gridpools are described under `assets.gridpools`, each entry naming the
  enterprise that owns the gridpool. `AssetsConfig.find_enterprise(gridpool_id)`
  returns the configured owner.
  `gridpool-cli find-enterprise <gridpool_id> <files>` prints it from the config.
  `AssetsConfig.check` enforces the one-enterprise-per-gridpool invariant: a
  gridpool's microgrids may not disagree on it, and a declared enterprise must
  match the inferred one.

- A config derived from the Assets API now carries each microgrid's
  `enterprise_id`.

- `generate-config --inplace` refreshes managed values while preserving
  formatting; `--fill-missing` only adds absent values. Generated patches are
  validated before writing.

# Frequenz Gridpool Library Release Notes

## Summary

<!-- Here goes a general summary of what this release is about -->

## Upgrading

- `MicrogridConfig.load_from_file` is replaced by `AssetsConfig.load_from_files`,
  which loads one or more files, merged into one document, and returns the whole
  document rather than just its microgrids:

  ```python
  configs = AssetsConfig.load_from_files(path).microgrids
  ```

  `load_configs` now returns the whole `AssetsConfig` rather than just its
  microgrids, so the file layers' `relations` and `market_locations` survive the
  merge; replace `load_configs(...)` with `load_configs(...).microgrids` where
  only the microgrid map is needed. `load_from_files` layers files field by field
  instead of replacing a complete microgrid entry; fields omitted by a later file
  retain the value from the earlier layer and cannot be removed by omission.

- `Metadata` is removed; its fields (`microgrid_id`, `name`, `gid`, coordinates,
  times) now sit directly on `MicrogridConfig`:

  ```python
  MicrogridConfig(microgrid_id=1, name="Grid")  # was meta=Metadata(...)
  ```

  In TOML they move up one level, `assets.microgrids.1.name` rather than
  `assets.microgrids.1.meta.name`. A file still nesting a microgrid's fields
  under `meta` loads, lifted with a deprecation warning.

- A microgrid's `delivery_area` is removed. Move its value to a relation's
  `delivery_area.code`, and set `delivery_area.code_type` when the code is not
  EIC. When relations are present, the legacy `gid` must be their sole
  gridpool ID; remove it for a microgrid that participates in several gridpools.

- `load_configs_from_files` is removed. Use `AssetsConfig.load_from_files`,
  which returns the whole document rather than just its microgrids: replace
  `load_configs_from_files(files)` with
  `AssetsConfig.load_from_files(files).microgrids`, or use the returned
  `AssetsConfig` directly to keep relations and market locations.

- `load_configs_from_api` is now private. For an API-only load call
  `load_configs(assets_client=..., microgrid_ids=...)` and read its `.microgrids`.

- `merge_config_maps` and `merge_microgrid_configs` are removed. Layering is now
  done on the raw tables before loading, inside `load_configs` and
  `AssetsConfig.load_from_files`; pass all the layers to one of those instead of
  merging loaded objects.

- Relation validity bounds and `at` query instants must include a UTC offset.

- The implementation modules `config.load` and `config.microgrid` are now
  private. Import their public names from `frequenz.gridpool.config` instead.

- Microgrids are now keyed by `int` microgrid ID, not `str`. This covers
  `AssetsConfig.microgrids`, including documents returned by `load_configs`.
  Index the mapping by integer ID:

  ```python
  configs[1]  # was configs["1"]
  ```

- The `AC_ACTIVE_POWER` deprecation warning is dropped. Use `AC_POWER_ACTIVE`
  as the formula metric key; the old name is no longer flagged on load.

## New Features

- `AssetsConfig` gives the `assets` namespace a type, so the entities still to
  come are added as fields rather than as more dict lookups. Microgrid IDs are
  checked during construction. `AssetsConfig.check()` performs the topology-wide
  checks after all layers have been merged; the file loaders call it unless
  `AssetsConfig.load_from_files` is passed `check=False`.

  File loaders ignore unknown entity tables with a warning, so a reader keeps
  working against files that already carry newer entities.

  The `assets` table may carry a `version`; on load a document is run through a
  migration pipeline that brings older layouts up to the current format, so
  legacy files keep working. The version tracks the assets format alone, not
  the whole document.

- Market topology is described under `assets.relations`, based on the Assets
  API `MarketTopologyRelation`: each record links at least two of a gridpool, a
  microgrid and a market location, filed under a
  `G<gridpool_id>M<microgrid_id>L<market_location_id>` key derived from its own
  sides. A relation naming a gridpool sits in a `delivery_area` that rides on
  the relation, so a gridpool-to-microgrid relation with no market location still
  carries one. A relation's validity lives in `validity`, each entry a half-open
  `[start, end)` datetime period it applies over. Use-case-specific periods
  qualify a relation; separate relations let one microgrid participate in
  several gridpools. The config extends the API with plain periods for relations
  that do not distinguish use cases. A gridpool-free microgrid-to-market-location
  relation may also carry a delivery area for a direct mapping. Market locations
  live under `assets.market_locations` as self-describing entries carrying their
  own identifier, how to read it (`MALO_ID` by default), and the Assets API market
  area (`EU_DE` by default). A relation's `delivery_area` is a `code` plus a
  `code_type` that defaults to EIC, so an EIC area is just
  `delivery_area.code = "..."`; EIC codes are check-character-validated. Raw
  market-location IDs must be unique within a document, including across market
  areas.

  `AssetsConfig` answers the common lookups with `find_relations` and the
  projections `find_delivery_areas`, `find_market_locations` and
  `find_microgrids`, each filtered by the other sides and an instant.

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

## Bug Fixes

- Layering config files no longer resets a field a later file leaves unset back
  to its default. The raw tables are merged before they are loaded.

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

# Frequenz Gridpool Library Release Notes

## Summary

<!-- Here goes a general summary of what this release is about -->

## Upgrading

- Microgrid config files should nest their entries under `assets.microgrids`:

  ```toml
  assets.microgrids.23.meta.name = "..."
  ```

  Bare microgrid IDs at the top level still load but log a deprecation warning,
  and support for them will be removed. The namespace keeps generated inventory
  data apart from operator settings under `app.*`, so a config file can carry
  both without its keys colliding.

  A file mixing both layouts is rejected.

## New Features

<!-- Here goes the main new features and examples or instructions on how to use them -->

## Bug Fixes

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

# Frequenz Gridpool Library Release Notes

## Summary

<!-- Here goes a general summary of what this release is about -->

## Upgrading

<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->

## New Features

<!-- Here goes the main new features and examples or instructions on how to use them -->

## Bug Fixes

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

# Frequenz Gridpool Library Release Notes

## Summary

This release updates the microgrid component graph library to v0.5.0 and adds a way to configure how the component graph is built.

## Upgrading

* The per-category formulas (`pv`, `battery`, `chp`, `ev`) now read the component first and use the meter as the fallback. This is the opposite of the old order, and it changes the generated config. Regenerate stored configs with this release and review the diff.
* To keep the old order, pass `ComponentGraphConfig(prefer_meters_in_component_formulas=True)` to `load_configs`, `load_configs_from_api` or `ComponentGraphGenerator`, or use the new `--prefer-meters-in-component-formulas` flag of the CLI.
* The update brings more changes, for example to the `consumption` formula and to the graph validation error messages. See the [v0.5.0 release notes](https://github.com/frequenz-floss/frequenz-microgrid-component-graph-python/releases/tag/v0.5.0) of the component graph library for the full list.

## New Features

* `load_configs` and `load_configs_from_api` take a `component_graph_config` argument, and `ComponentGraphGenerator` takes it as `config`. It controls how the component graph is built and how its formulas are generated. `ComponentGraphConfig` and `FormulaOverrides` are re-exported from `frequenz.gridpool` and `frequenz.gridpool.config`.
* The `generate-config` and `print-formulas` CLI commands take a `--prefer-meters-in-component-formulas` flag, which reads the meter before the component in the per-category formulas.

## Bug Fixes

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

# Frequenz Gridpool Library Release Notes

## Summary

<!-- Here goes a general summary of what this release is about -->

## Upgrading

- This updates the component-graph library to v0.5.0, which now needs `frequenz-client-assets` >= 0.3.1. It changes the generated per-category formulas, so regenerate stored configs with this release and review the diff.

  - The formula fallback engine was rewritten. Formulas can now use meter subtraction as a fallback, which gives better fallback coverage. The exact formula strings can differ from the previous release, even for the same graph.
  - The per-category formulas (`pv`, `battery`, `chp`, `ev`) now read the component first and use the meter as the fallback. This is the opposite of the previous order.

  See the [v0.5.0 release notes](https://github.com/frequenz-floss/frequenz-microgrid-component-graph-python/releases/tag/v0.5.0) of the component graph library for the full list of changes.

## New Features

<!-- Here goes the main new features and examples or instructions on how to use them -->

## Bug Fixes

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

# Frequenz Gridpool Library Release Notes

## Summary

<!-- Here goes a general summary of what this release is about -->

## Upgrading

- This updates the component-graph library to v0.5.0, which now needs `frequenz-client-assets` >= 0.3.1. It changes the generated per-category formulas, so regenerate stored configs with this release and review the diff.

  - The formula fallback engine was rewritten. Formulas can now use meter subtraction as a fallback, which gives better fallback coverage. The exact formula strings can differ from the previous release, even for the same graph.
  - The per-category formulas (`pv`, `battery`, `chp`, `ev`) now read the component first and use the meter as the fallback. This is the opposite of the previous order.

  See the [v0.5.0 release notes](https://github.com/frequenz-floss/frequenz-microgrid-component-graph-python/releases/tag/v0.5.0) of the component graph library for the full list of changes.

## New Features

<!-- Here goes the main new features and examples or instructions on how to use them -->

## Bug Fixes

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

# Frequenz Gridpool Library Release Notes

## Summary

<!-- Here goes a general summary of what this release is about -->

## Upgrading

<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->

## New Features

* Added an `--inplace` flag to the `generate-config` CLI command: patches `--default` directly instead of printing to stdout, only filling in values it's missing so existing comments, field order and formatting survive untouched.
* `generate-config` now renders whole-number values (e.g. peak/rated power) as underscore-grouped ints (`1_736_680`) instead of floats (`1736680.0`), avoiding spurious diffs.

## Bug Fixes

<!-- Here goes notable bug fixes that are worth a special mention or explanation -->