# 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 -->

# Frequenz Gridpool Library Release Notes

## Summary

This release reworks the microgrid configuration loading API: the loaders are now module-level functions exported from `frequenz.gridpool` for loading configs from files, from the Assets API, or from both layered together. It also adds a `generate-config` CLI command.

## Upgrading

The configuration loaders are no longer `MicrogridConfig` static methods — they are module-level functions exported from `frequenz.gridpool`, and their signatures have changed:

* `MicrogridConfig.load_configs(files, dir)` → `load_configs_from_files(files)`. The `microgrid_config_dir` argument has been removed; pass an explicit list of files instead, e.g. `load_configs_from_files(list(Path(my_dir).glob("*.toml")))`. Note that the name `load_configs` now refers to the new merge wrapper (see New Features), not the file loader.
* `MicrogridConfig.load_configs_with_formulas(assets_url, assets_auth_key, assets_sign_secret, files, dir)` → `load_configs(default_files=files, assets_client=client, override_files=...)`. It now takes an `AssetsApiClient` you construct instead of raw credentials, and layers its sources by explicit precedence (default files < Assets API < override files) rather than the old "load files, then fill in missing formulas" behavior.
* The CLI dependencies (`asyncclick` and the new `tomlkit`) are no longer core dependencies; they have moved to a `cli` optional extra. Install the CLI with `pip install frequenz-gridpool[cli]` (the `render-graph` extra now pulls this in automatically).

## New Features

* Added config loading functions, exported from `frequenz.gridpool`:
   * `load_configs_from_files(...)` loads microgrid configs from one or more TOML files.
   * `load_configs_from_api(...)` loads microgrid metadata (latitude/longitude) from the Assets API and derives the per-type formulas and meter/inverter/component IDs directly from the component graph. The two steps fail independently: a microgrid whose metadata cannot be fetched is skipped, while one whose component graph cannot be derived is still returned with metadata only. Both are logged rather than aborting the whole batch.
   * `load_configs(...)` loads from up to three layered sources — default files, the Assets API, and override files — and merges them, with higher layers winning on conflicts. The microgrid IDs fetched from the Assets API can be given explicitly or are otherwise taken from the files.
* Added `merge_microgrid_configs(...)` for deep-merging two `MicrogridConfig` objects where override values take precedence and `None` does not overwrite base values.
* Added `merge_config_maps(...)` for merging two dictionaries of microgrid configs by microgrid ID.
* Added a `generate-config` CLI command that derives a microgrid config from the Assets API and prints it as TOML, optionally layering `--default` and `--override` config files by precedence (`--default` < Assets API < `--override`).

## 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

* Add start and end time to microgrid configs.

## 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

* Change the `curtailable` flag default of the PV config to `None`.

## 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

## Upgrading

- This updates the component-graph version to 0.4, which breaks the config format for component graphs when there are created.