diff --git a/README.md b/README.md index 5511c92f..47d3b01f 100644 --- a/README.md +++ b/README.md @@ -1,251 +1,135 @@ -# network-modification +# GridSuite Network Modification [![Actions Status](https://github.com/gridsuite/network-modification/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/gridsuite/network-modification/actions) [![Coverage Status](https://sonarcloud.io/api/project_badges/measure?project=org.gridsuite%3Anetwork-modification&metric=coverage)](https://sonarcloud.io/component_measures?id=org.gridsuite%3Anetwork-modification&metric=coverage) [![MPL-2.0 License](https://img.shields.io/badge/license-MPL_2.0-blue.svg)](https://www.mozilla.org/en-US/MPL/2.0/) -## Architecture +## Overview -This library is organized around two distinct responsibilities that must not be confused: +`gridsuite-network-modification` is a Java library designed to apply structural, operational, and topological modifications to electrical power networks. As a core component of the [GridSuite](http://www.gridsuite.org/) platform, it is built on top of [PowSyBl](https://www.powsybl.org/) (Power System Blocks). -- **Describing** a modification — the serializable input data exchanged over REST and persisted by the - server (the `dto` package, suffixed `*Infos`). -- **Applying** a modification — the executable logic that mutates a PowSyBl `Network` (the `modifications` - package). +The library provides a clean separation of concerns: +- **Data Transfer Objects (DTOs)**: Model modification requests, rules, and configurations (e.g., equipment creation, deletion, parameter adjustments, filter/formula-based modifications, and tabular changes). +- **Modification Implementations**: Execute the business logic that mutates a PowSyBl `Network` model. +- **Reporting & Validation**: Integrated i18n reporting (PowSyBl `ReportNode`) and constraint validation. -Keeping these two concerns separated is the central design goal: it lets the *execution* code stand on its -own, ultimately as a standalone library that does not need the server-oriented DTO layer. +## Technology Stack -### Package layout +- **Language**: Java 25 (configured in `pom.xml`) +- **Build & Dependency Management**: Apache Maven +- **Core Power System Framework**: [PowSyBl](https://www.powsybl.org/) (IIDM API/Implementation, Load-Flow API, Open Load-Flow, Balances Adjustment) +- **Serialization & Validation**: Jackson, Swagger/OpenAPI v3 annotations, Jakarta Validation API +- **Scripting & Expressions**: Apache Groovy +- **Code Generation**: Project Lombok +- **Testing**: JUnit 5, Spring Boot Test, PowSyBl Config Test, JaCoCo -``` -org.gridsuite.modification -├── (root) Cross-cutting contracts & enums: NetworkModificationException, -│ ModificationType, IFilterService, ILoadFlowService, VariationMode, … -├── modifications The execution layer. One class per modification (e.g. LoadCreation), -│ │ each extending AbstractModification and implementing apply(Network, …). -│ ├── data Plain data holders that belong to the execution layer but are not yet -│ │ moved out of dto (see "Shared data objects" below). -│ ├── byfilter "By filter" / "by formula" modification execution. -│ ├── tabular Tabular (bulk) modification execution — special case, see below. -│ └── olg Operational-limits-group execution helpers. -├── dto The description layer. One *Infos class per modification, all extending -│ │ ModificationInfos. REST contract (Swagger) + JPA/serialization model. -│ ├── annotation DTO annotations (@ModificationErrorTypeName, …). -│ ├── byfilter DTO for by-filter/by-formula modifications. -│ └── tabular DTO for tabular modifications. -├── utils Stateless helpers operating on the network (ModificationUtils, …). -└── report PowSyBl report resource bundle. -``` +## Requirements -### The two layers and the bridge between them +- **JDK**: Java 25 or higher +- **Maven**: Version 3.8.x or higher -Every modification exists as a pair: +## Setup and Installation -| Layer | Example | Base class | Role | -|--------------|------------------|-----------------------|------------------------------------------------------------| -| `dto` | `LoadCreationInfos` | `ModificationInfos` | Serializable description: REST contract, persistence, Swagger. | -| `modifications` | `LoadCreation` | `AbstractModification` | Executable logic: `check(network)` then `apply(network, …)`. | +### Adding as a Maven Dependency -`ModificationInfos` is the polymorphic root of the DTO layer (`@JsonTypeInfo` + `@JsonSubTypes`); it carries -the server-specific fields (`uuid`, `date`, `stashed`, `activated`, `messageType`, `messageValues`, -`description`) and the Swagger annotations. +Add the following dependency to your project's `pom.xml`: -The single bridge from description to execution is `ModificationInfos#toModification()`. Each leaf `*Infos` -builds its matching modification from its own fields: - -```java -// LoadCreationInfos -public AbstractModification toModification() { - return LoadCreation.builder() - .equipmentId(getEquipmentId()) - .p0(p0) - .q0(q0) - // … copy every field … - .build(); -} +```xml + + org.gridsuite + gridsuite-network-modification + version_to_use + ``` -This is why the modification classes **redeclare their business fields** instead of inheriting them from the -`*Infos` DTO: it severs the dependency from `modifications` to the server-oriented `ModificationInfos` -hierarchy. The modification is a self-contained, builder-constructed object; the DTO merely knows how to -populate it. - -### Class hierarchy +### Building Locally -Both layers mirror the same equipment taxonomy, but in two independent trees. - -#### Execution layer (`modifications`) - -Every applied modification descends from `AbstractModification` (itself a PowSyBl -`AbstractNetworkModification`). The abstract bases factor out the shared `check`/`apply`/reporting logic: +To build and install the library into your local Maven repository (`~/.m2/repository`): +```bash +mvn clean install ``` -AbstractNetworkModification (powsybl) -└── AbstractModification - ├── AbstractEquipmentBase - │ ├── AbstractEquipmentCreation - │ │ ├── AbstractInjectionCreation ........ implements InjectionCreation - │ │ │ ├── LoadCreation - │ │ │ ├── GeneratorCreation ............ implements ReactiveLimitsHolderInfos - │ │ │ ├── BatteryCreation .............. implements ReactiveLimitsHolderInfos - │ │ │ ├── ShuntCompensatorCreation - │ │ │ └── StaticVarCompensatorCreation - │ │ ├── AbstractBranchCreation - │ │ │ ├── LineCreation - │ │ │ └── TwoWindingsTransformerCreation - │ │ ├── SubstationCreation - │ │ ├── VoltageLevelCreation - │ │ ├── LccCreation - │ │ └── VscCreation - │ ├── AbstractEquipmentModification - │ │ ├── AbstractInjectionModification .... implements InjectionModification - │ │ │ ├── LoadModification - │ │ │ ├── GeneratorModification - │ │ │ ├── BatteryModification - │ │ │ └── ShuntCompensatorModification - │ │ ├── AbstractBranchModification - │ │ │ ├── LineModification - │ │ │ └── TwoWindingsTransformerModification - │ │ ├── SubstationModification - │ │ ├── VoltageLevelModification - │ │ ├── LccModification - │ │ └── VscModification - │ ├── EquipmentAttributeModification - │ ├── EquipmentDeletion - │ ├── OperatingStatusModification - │ └── VoltageLevelTopologyModification - ├── AbstractScaling - │ ├── GeneratorScaling - │ └── LoadScaling - └── (standalone) CompositeModification, ModificationReference, GroovyScript, - GenerationDispatch, ByFilterDeletion, VoltageInitModification, … -``` - -#### Shared contracts: `InjectionCreation` / `InjectionModification` -The `InjectionCreation` and `InjectionModification` **interfaces** (in `modifications`) declare the common -injection field accessors (`equipmentId`, `voltageLevelId`, properties, connection info, …). They are -implemented by **two independent abstract bases**, which is the reason the contract is an interface rather -than a shared superclass: - -- `modifications.AbstractInjectionCreation` — the base for *top-level* injection modifications (above). -- `modifications.data.AbstractInjectionCreation` — a base for *injection data components* that are **not** - modifications themselves. `LccConverterStationCreation` and `VscConverterStationCreation` extend it; they - are sub-objects embedded inside `LccCreation` / `VscCreation` rather than standalone modifications, which - is why they live in `modifications.data` and only implement the interface instead of joining the - `AbstractModification` chain. - -`ReactiveLimitsHolderInfos` is another shared interface (currently in `dto`) implemented by the -reactive-limits-bearing creations (`GeneratorCreation`, `BatteryCreation`, `VscConverterStationCreation`). +## Build and Scripts Commands + +Common Maven commands for development and CI: + +- **Compile sources**: + ```bash + mvn clean compile + ``` +- **Package JAR**: + ```bash + mvn package + ``` +- **Run Checkstyle validation**: + ```bash + mvn checkstyle:check + ``` +- **Generate JaCoCo coverage report**: + ```bash + mvn test jacoco:report + ``` + +## Environment Variables + +This project is a library and does not require standalone runtime environment variables. However, standard build/tooling configuration applies: + +| Variable | Description | Default / Example | +|---|---|---| +| `JAVA_HOME` | Path to JDK 25 installation directory | `/path/to/jdk-25` | +| `MAVEN_OPTS` | JVM options passed to Maven builds | `-Xmx2048m` | +| `SONAR_TOKEN` | SonarCloud authentication token (used in CI) | Secret / CI only | +| `REPO_ACCESS_TOKEN` | Repository access token (used in CI release workflows) | Secret / CI only | + +## Tests + +The project includes unit and integration tests covering modifications, DTO serialization, formula evaluation, and report generation. + +To run tests: +```bash +mvn test +``` -#### Description layer (`dto`) +To run a specific test class: +```bash +mvn test -Dtest=ModificationTest +``` -The DTO tree parallels the execution tree, rooted at the polymorphic `ModificationInfos`: +## Project Structure ``` -ModificationInfos -├── EquipmentModificationInfos -│ ├── EquipmentCreationInfos -│ │ ├── InjectionCreationInfos -│ │ │ ├── LoadCreationInfos -│ │ │ ├── GeneratorCreationInfos ........... implements ReactiveLimitsHolderInfos -│ │ │ ├── BatteryCreationInfos ............. implements ReactiveLimitsHolderInfos -│ │ │ ├── ShuntCompensatorCreationInfos -│ │ │ ├── StaticVarCompensatorCreationInfos -│ │ │ ├── LccConverterStationCreationInfos -│ │ │ └── ConverterStationCreationInfos .... implements ReactiveLimitsHolderInfos -│ │ ├── BranchCreationInfos -│ │ │ ├── LineCreationInfos -│ │ │ └── TwoWindingsTransformerCreationInfos -│ │ ├── SubstationCreationInfos -│ │ ├── VoltageLevelCreationInfos -│ │ └── LccCreationInfos -│ ├── BasicEquipmentModificationInfos -│ │ ├── InjectionModificationInfos -│ │ │ ├── LoadModificationInfos -│ │ │ ├── GeneratorModificationInfos -│ │ │ └── … (Battery, ShuntCompensator, ConverterStation, Lcc, …) -│ │ ├── BranchModificationInfos -│ │ │ ├── LineModificationInfos -│ │ │ └── TwoWindingsTransformerModificationInfos -│ │ └── SubstationModificationInfos -│ ├── EquipmentAttributeModificationInfos -│ ├── EquipmentDeletionInfos -│ └── OperatingStatusModificationInfos -├── ScalingInfos -│ ├── GeneratorScalingInfos -│ └── LoadScalingInfos -└── (direct) CompositeModificationInfos, ModificationReferenceInfos, GroovyScriptInfos, - TabularModificationInfos, ByFilterDeletionInfos, VoltageInitModificationInfos, … +gridsuite-network-modification +├── .github/workflows/ # GitHub Actions CI/CD workflows +├── docs/ # Detailed architectural and API documentation +│ ├── API.md # API reference +│ └── ARCHITECTURE.md # Architecture documentation +├── src/ +│ ├── main/ +│ │ ├── java/ +│ │ │ └── org/gridsuite/modification/ +│ │ │ ├── dto/ # Data Transfer Objects (deserialization, models) +│ │ │ ├── error/ # Exception types and error handling +│ │ │ ├── modifications/ # Concrete modification business logic +│ │ │ ├── report/ # Report bundles and i18n support +│ │ │ ├── utils/ # Utility classes and helpers +│ │ │ ├── IFilterService.java +│ │ │ └── ILoadFlowService.java +│ │ ├── java-templates/ # Version templates processed at build time +│ │ └── resources/ # Internationalization and message bundles +│ └── test/ +│ ├── java/ # Unit and integration test suites +│ └── resources/ # Test configurations and network fixtures +├── pom.xml # Maven project configuration +├── LICENSE # Mozilla Public License 2.0 +└── README.md # Repository documentation ``` -Note the two trees are **not** linked by inheritance: a `LoadCreation` is *not* a subclass of -`LoadCreationInfos`. They are connected only through `LoadCreationInfos.toModification()`, which copies the -DTO's fields into a freshly built `LoadCreation`. +## Documentation -### Dependency rules between packages - -The dependency direction is deliberate and one-way: - -``` - dto ───────────────► modifications ───► utils ───► (root contracts) - (description) (execution) -``` +- [Architecture Overview](docs/ARCHITECTURE.md) +- [API Reference](docs/API.md) -- **`dto` depends on `modifications`** — every `*Infos.toModification()` constructs a concrete modification. - This is expected and correct. -- **`modifications` must NOT depend on `ModificationInfos` subclasses.** The execution layer should never - reference a server-oriented DTO. Today, after redeclaring the business fields in the modifications, this - rule holds for the whole creation/modification family. -- The only `dto` types the `modifications` package is still allowed to reference are **plain data objects** - that happen to live in `dto` for now — see below. - -#### Shared data objects (the `dto` types modifications may still use) - -A handful of `dto` classes are *not* modifications: they are simple, reusable value/data objects that do -**not** extend `ModificationInfos`. The execution layer references them legitimately, for example: - -- `FreePropertyInfos`, `AttributeModification`, `ReactiveCapabilityCurvePointsInfos`, - `IdentifiableAttributes`, `ScalingVariationInfos`, `FilterInfos`, `OperationalLimitsGroupInfos`, … - -These currently sit in the `dto` package only for historical reasons. Conceptually they belong to the -execution model and are **intended to move into the `modifications` package** (the `modifications.data` -subpackage already hosts some of them, e.g. the injection creation/modification data holders and the LCC/VSC -converter-station data). Until that move is complete, treat any `dto` type that does **not** extend -`ModificationInfos` as part of the execution model, not as a DTO. - -The same applies to **value types nested inside an `*Infos` class**: a modification that imports an `*Infos` -purely to reach a nested enum or record is *not* depending on a `ModificationInfos` subclass — it is using a -plain data object that simply lives in the wrong place. For example `OperatingStatusModification` references -only `OperatingStatusModificationInfos.ActionType`, a plain enum. Such nested types should be promoted to -top-level data objects and moved alongside the execution layer (`modifications.data`). - -### Special cases: composite, tabular & reference modifications - -A few families break the "modifications never depend on `ModificationInfos`" rule by nature, and are -explicitly **excluded** from it: - -- **`CompositeModification`** aggregates an ordered list of child modifications. -- **Tabular modifications** (`modifications.tabular`) apply the same modification to many equipments in bulk. -- **`ModificationReference`** wraps a single other modification, holding it as a `ModificationInfos` and - delegating to its `toModification()` at apply time. - -All of these are *containers of modifications*, so they intrinsically manipulate the polymorphic -`ModificationInfos` type (and the tabular `*Infos`). They should be understood as a layer *above* the -ordinary modifications rather than peers of them, and they are not expected to satisfy the -"no `ModificationInfos` dependency" constraint that applies to every other modification. - -### Adding a new modification - -1. Create the executable `XxxModification` (or `XxxCreation`) in `modifications`, extending - `AbstractModification`. Declare its own business fields, implement `check(Network)` and - `apply(Network, ReportNode)`, expose a Lombok `@Builder`. -2. Create the `XxxInfos` DTO in `dto`, extending the appropriate `ModificationInfos` subtype, carrying the - Swagger annotations and any persistence concerns. -3. Implement `XxxInfos#toModification()` to build the modification from the DTO's fields. -4. Register the DTO in the `@JsonSubTypes` list of `ModificationInfos` and add its `@JsonTypeName` / - `@ModificationErrorTypeName` annotations. -5. Reuse the shared data objects (`FreePropertyInfos`, `AttributeModification`, …) for common fields; do not - let the modification reference any `ModificationInfos` subclass. +## License +This project is licensed under the [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/) (MPL-2.0). See the [LICENSE](LICENSE) file for details. diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 00000000..1d89d064 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,872 @@ +# API Reference — `gridsuite-network-modification` + +--- + +## Table of Contents + +1. [Core Interfaces](#1-core-interfaces) +2. [AbstractModification Lifecycle](#2-abstractmodification-lifecycle) +3. [ModificationInfos — Base DTO](#3-modificationinfos--base-dto) +4. [ModificationType Enum](#4-modificationtype-enum) +5. [DTO Hierarchy & Field References](#5-dto-hierarchy--field-references) + - 5.1 [Equipment Modification DTOs](#51-equipment-modification-dtos) + - 5.2 [Equipment Creation Base DTOs](#52-equipment-creation-base-dtos) + - 5.3 [Injection Creation DTOs](#53-injection-creation-dtos) + - 5.4 [Branch Creation DTOs](#54-branch-creation-dtos) + - 5.5 [Injection Modification DTOs](#55-injection-modification-dtos) + - 5.6 [Branch Modification DTOs](#56-branch-modification-dtos) + - 5.7 [Substation & Voltage Level DTOs](#57-substation--voltage-level-dtos) + - 5.8 [HVDC DTOs](#58-hvdc-dtos) + - 5.9 [Topology Modification DTOs](#59-topology-modification-dtos) + - 5.10 [Deletion DTOs](#510-deletion-dtos) + - 5.11 [Scaling & Dispatch DTOs](#511-scaling--dispatch-dtos) + - 5.12 [Bulk & Programmatic Modification DTOs](#512-bulk--programmatic-modification-dtos) + - 5.13 [Operational Modification DTOs](#513-operational-modification-dtos) + - 5.14 [Composition & Reference DTOs](#514-composition--reference-dtos) +6. [Supporting Value Objects](#6-supporting-value-objects) +7. [Exceptions & Error Types](#7-exceptions--error-types) +8. [Enumerations Reference](#8-enumerations-reference) +9. [Usage Examples](#9-usage-examples) + +--- + +## 1. Core Interfaces + +### `IFilterService` + +**Package:** `org.gridsuite.modification` + +Interface to decouple filter evaluation and remote filter service resolution from the core modification engine. + +```java +public interface IFilterService { + + /** + * Fetches filter definitions by their UUIDs. + * + * @param filtersUuids list of filter UUIDs + * @return list of AbstractFilter objects + */ + List getFilters(List filtersUuids); + + /** + * Resolves filters against a live network and streams matching equipment. + * + * @param filtersUuids list of filter UUIDs + * @param network the network to resolve against + * @return stream of matched equipment per filter + */ + Stream exportFilters( + List filtersUuids, Network network); + + /** + * Returns a map from filter UUID to the equipment matched by that filter. + * + * @param network the network to resolve against + * @param filters map of filter UUID → filter name + * @return map of filter UUID → FilterEquipments + */ + Map getUuidFilterEquipmentsMap(Network network, Map filters); +} +``` + +--- + +### `ILoadFlowService` + +**Package:** `org.gridsuite.modification` + +Interface for retrieving stored load-flow parameters by UUID for modifications that execute power flow simulations. + +```java +public interface ILoadFlowService { + + /** + * Retrieves load-flow parameters by UUID. + * + * @param loadFlowParametersUuid the UUID of the stored parameters + * @return LoadFlowParametersInfos populated with all load-flow settings + */ + LoadFlowParametersInfos getLoadFlowParametersInfos(UUID loadFlowParametersUuid); +} +``` + +--- + +## 2. `AbstractModification` Lifecycle + +**Package:** `org.gridsuite.modification.modifications` +**Extends:** `com.powsybl.iidm.modification.AbstractNetworkModification` + +The abstract base class for all concrete modification implementations. + +### Methods + +| Method | Description | +|---|---| +| `void check(Network network)` | Validates inputs and constraints against the live network. Throws `NetworkModificationException` on conflict or missing prerequisites. Default implementation does nothing. | +| `void initApplicationContext(IFilterService filterService, ILoadFlowService loadFlowService)` | Injects external service instances. Called prior to `check` when service dependencies exist. Default implementation does nothing. | +| `void apply(Network network, ReportNode subReportNode)` | Mutates the `Network` and logs structured progress and audit messages to `subReportNode`. | +| `void apply(Network network, NamingStrategy namingStrategy, ReportNode subReportNode)` | Variant supporting a custom naming strategy. Defaults to delegating to `apply(network, subReportNode)`. | +| `String getName()` | Returns the descriptive name for the modification type. | + +--- + +## 3. `ModificationInfos` — Base DTO + +**Package:** `org.gridsuite.modification.dto` +**JSON Discriminator Property:** `type` (matches `ModificationType` enum name) + +### Fields + +| Field | Type | Description | +|---|---|---| +| `uuid` | `UUID` | Unique identifier of this modification instance | +| `type` | `ModificationType` | Discriminator property; automatically derived from `@JsonTypeName` on concrete subclasses | +| `date` | `Instant` | Creation or update timestamp | +| `stashed` | `Boolean` | Staging flag (default `false`). When `true`, skipped during execution | +| `activated` | `Boolean` | Activation flag (default `true`). When `false`, skipped during execution | +| `description` | `String` | Optional free-text description | +| `messageType` | `String` | i18n message template key | +| `messageValues` | `String` | Serialized message interpolation parameters | + +### Methods + +| Method | Description | +|---|---| +| `AbstractModification toModification()` | Factory method instantiating the corresponding `AbstractModification`. | +| `ReportNode createSubReportNode(ReportNode reportNode)` | Creates and attaches a child `ReportNode` with the appropriate message template. | +| `void check()` | Validates internal DTO fields before conversion. | +| `ModificationType getType()` | Returns the modification type enum value. | +| `Map getMapMessageValues()` | Returns message interpolation values as key-value pairs. | + +--- + +## 4. `ModificationType` Enum + +**Package:** `org.gridsuite.modification` + +Supported modification types in `ModificationType.java`: + +| Modification Type | Category | +|---|---| +| `LOAD_CREATION` | Injections | +| `LOAD_MODIFICATION` | Injections | +| `BATTERY_CREATION` | Injections | +| `BATTERY_MODIFICATION` | Injections | +| `GENERATOR_CREATION` | Injections | +| `GENERATOR_MODIFICATION` | Injections | +| `SHUNT_COMPENSATOR_CREATION` | Injections | +| `SHUNT_COMPENSATOR_MODIFICATION` | Injections | +| `STATIC_VAR_COMPENSATOR_CREATION` | Injections | +| `LINE_CREATION` | Branches | +| `LINE_MODIFICATION` | Branches | +| `TWO_WINDINGS_TRANSFORMER_CREATION` | Branches | +| `TWO_WINDINGS_TRANSFORMER_MODIFICATION` | Branches | +| `SUBSTATION_CREATION` | Substations & Voltage Levels | +| `SUBSTATION_MODIFICATION` | Substations & Voltage Levels | +| `VOLTAGE_LEVEL_CREATION` | Substations & Voltage Levels | +| `VOLTAGE_LEVEL_MODIFICATION` | Substations & Voltage Levels | +| `VSC_CREATION` | HVDC | +| `VSC_MODIFICATION` | HVDC | +| `CONVERTER_STATION_CREATION` | HVDC | +| `CONVERTER_STATION_MODIFICATION` | HVDC | +| `LCC_CREATION` | HVDC | +| `LCC_MODIFICATION` | HVDC | +| `LCC_CONVERTER_STATION_CREATION` | HVDC | +| `LCC_CONVERTER_STATION_MODIFICATION` | HVDC | +| `EQUIPMENT_DELETION` | Deletion | +| `BY_FILTER_DELETION` | Deletion | +| `LINE_SPLIT_WITH_VOLTAGE_LEVEL` | Topology | +| `LINE_ATTACH_TO_VOLTAGE_LEVEL` | Topology | +| `LINES_ATTACH_TO_SPLIT_LINES` | Topology | +| `DELETE_VOLTAGE_LEVEL_ON_LINE` | Topology | +| `DELETE_ATTACHING_LINE` | Topology | +| `VOLTAGE_LEVEL_TOPOLOGY_MODIFICATION` | Topology | +| `CREATE_COUPLING_DEVICE` | Topology | +| `CREATE_VOLTAGE_LEVEL_TOPOLOGY` | Topology | +| `CREATE_VOLTAGE_LEVEL_SECTION` | Topology | +| `MOVE_VOLTAGE_LEVEL_FEEDER_BAYS` | Topology | +| `GENERATOR_SCALING` | Scaling & Dispatch | +| `LOAD_SCALING` | Scaling & Dispatch | +| `GENERATION_DISPATCH` | Scaling & Dispatch | +| `BALANCES_ADJUSTMENT_MODIFICATION` | Operational | +| `OPERATING_STATUS_MODIFICATION` | Operational | +| `VOLTAGE_INIT_MODIFICATION` | Operational | +| `EQUIPMENT_ATTRIBUTE_MODIFICATION` | Bulk & Programmatic | +| `GROOVY_SCRIPT` | Bulk & Programmatic | +| `TABULAR_MODIFICATION` | Bulk & Programmatic | +| `TABULAR_CREATION` | Bulk & Programmatic | +| `LIMIT_SETS_TABULAR_MODIFICATION` | Bulk & Programmatic | +| `BY_FORMULA_MODIFICATION` | Bulk & Programmatic | +| `MODIFICATION_BY_ASSIGNMENT` | Bulk & Programmatic | +| `COMPOSITE_MODIFICATION` | Composition & Reference | +| `MODIFICATION_REFERENCE` | Composition & Reference | + +--- + +## 5. DTO Hierarchy & Field References + +### 5.1 Equipment Modification DTOs + +#### `EquipmentModificationInfos` ← `ModificationInfos` + +Base class for modifications targeting an existing equipment entity. + +| Field | Type | Description | +|---|---|---| +| `equipmentId` | `String` | **Required.** Identifier of the target equipment | +| `properties` | `List` | Custom key-value properties to assign or delete | + +#### `BasicEquipmentModificationInfos` ← `EquipmentModificationInfos` + +Lightweight DTO for simple equipment property alterations. + +--- + +### 5.2 Equipment Creation Base DTOs + +#### `EquipmentCreationInfos` ← `EquipmentModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `equipmentName` | `String` | Human-readable name for the new equipment | + +#### `InjectionCreationInfos` ← `EquipmentCreationInfos` + +Base class for injection equipment creations. + +| Field | Type | Description | +|---|---|---| +| `voltageLevelId` | `String` | **Required.** Voltage level identifier | +| `busOrBusbarSectionId` | `String` | **Required.** Bus (bus-breaker) or busbar section (node-breaker) identifier | +| `connectionName` | `String` | Feeder connection name | +| `connectionDirection` | `ConnectablePosition.Direction` | Direction: `TOP`, `BOTTOM`, or `UNDEFINED` | +| `connectionPosition` | `Integer` | Feeder position index in the bay | +| `terminalConnected` | `Boolean` | Initial connection status (default `true`) | + +#### `BranchCreationInfos` ← `EquipmentCreationInfos` + +Base class for branch equipment creations (lines, transformers). + +| Field | Type | Description | +|---|---|---| +| `voltageLevelId1` / `voltageLevelId2` | `String` | Voltage level ID at terminals 1 & 2 | +| `busOrBusbarSectionId1` / `Id2` | `String` | Bus/busbar section ID at terminals 1 & 2 | +| `connectionName1` / `Name2` | `String` | Connection name at terminals 1 & 2 | +| `connectionDirection1` / `Direction2` | `ConnectablePosition.Direction` | Connection direction at terminals 1 & 2 | +| `connectionPosition1` / `Position2` | `Integer` | Feeder position order at terminals 1 & 2 | +| `connected1` / `connected2` | `Boolean` | Connection status at terminals 1 & 2 | +| `currentLimits1` / `currentLimits2` | `CurrentLimitsInfos` | Permanent and temporary current limits at terminals 1 & 2 | + +--- + +### 5.3 Injection Creation DTOs + +#### `LoadCreationInfos` ← `InjectionCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `loadType` | `LoadType` | `UNDEFINED`, `AUXILIARY`, `FICTITIOUS` | +| `p0` | `double` | Active power consumption (MW) | +| `q0` | `double` | Reactive power consumption (MVar) | + +#### `GeneratorCreationInfos` ← `InjectionCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `energySource` | `EnergySource` | `HYDRO`, `NUCLEAR`, `WIND`, `SOLAR`, `THERMAL`, `OTHER`, … | +| `minP` / `maxP` | `double` | Minimum / maximum active power output (MW) | +| `ratedS` | `Double` | Rated nominal apparent power (MVA) | +| `targetP` | `double` | Active power set point (MW) | +| `targetQ` | `Double` | Reactive power set point (MVar) | +| `voltageRegulationOn` | `boolean` | Voltage regulation enabled | +| `targetV` | `Double` | Voltage set point (kV) | +| `minQ` / `maxQ` | `Double` | Minimum / maximum reactive power limits (MVar) | +| `plannedActivePowerSetPoint` | `Double` | Planned active power set point | +| `marginalCost` | `Double` | Marginal generation cost | +| `plannedOutageRate` / `forcedOutageRate` | `Double` | Outage rates | +| `reactiveCapabilityCurvePoints` | `List` | Reactive capability curve definition | +| `regulatingTerminalId` | `String` | Remote terminal ID for regulation | +| `regulatingTerminalType` | `String` | Remote terminal equipment type | +| `regulatingTerminalVlId` | `String` | Remote terminal voltage level ID | +| `qPercent` | `Double` | Reactive droop coefficient | +| `stepUpTransformerX` | `Double` | Step-up transformer reactance (Ω) | +| `directTransX` | `Double` | Direct-axis transient reactance | +| `participate` | `Boolean` | Participation in frequency control | +| `droop` | `Float` | Frequency droop coefficient | + +#### `BatteryCreationInfos` ← `InjectionCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `minP` / `maxP` | `double` | Active power limits (MW) | +| `targetP` / `targetQ` | `double` / `Double` | Active / reactive power set points | +| `participate` | `Boolean` | Frequency control participation | +| `droop` | `Float` | Frequency droop coefficient | +| `minQ` / `maxQ` | `Double` | Reactive power limits | +| `reactiveCapabilityCurvePoints` | `List` | Reactive capability curve points | + +#### `ShuntCompensatorCreationInfos` ← `InjectionCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `maxSusceptance` | `Double` | Maximum susceptance (S) | +| `maxQAtNominalV` | `Double` | Maximum reactive power at nominal voltage (MVar) | +| `shuntCompensatorType` | `ShuntCompensatorType` | `CAPACITOR` or `REACTOR` | +| `sectionCount` / `maximumSectionCount` | `Integer` | Current and maximum section count | +| `regulatingTerminalId` / `Type` / `VlId` | `String` | Regulating terminal descriptor | +| `voltageSetpoint` | `Double` | Voltage set point (kV) | +| `qPercent` | `Double` | Reactive droop percentage | + +#### `StaticVarCompensatorCreationInfos` ← `InjectionCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `minSusceptance` / `maxSusceptance` | `Double` | Susceptance boundaries (S) | +| `minQ` / `maxQ` | `Double` | Reactive power boundaries (MVar) | +| `regulationMode` | `StaticVarCompensator.RegulationMode` | `VOLTAGE`, `REACTIVE_POWER`, `OFF` | +| `voltageSetpoint` | `Double` | Target voltage set point (kV) | +| `reactivePowerSetpoint` | `Double` | Target reactive power set point (MVar) | +| `voltageRegulationType` | `VoltageRegulationType` | `LOCAL` or `DISTANT` | +| `regulatingTerminalId` / `Type` / `VlId` | `String` | Remote regulation terminal properties | + +--- + +### 5.4 Branch Creation DTOs + +#### `LineCreationInfos` ← `BranchCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `r` | `double` | Series resistance (Ω) | +| `x` | `double` | Series reactance (Ω) | +| `g1` / `b1` | `double` | Shunt conductance / susceptance at terminal 1 (S) | +| `g2` / `b2` | `double` | Shunt conductance / susceptance at terminal 2 (S) | + +#### `TwoWindingsTransformerCreationInfos` ← `BranchCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `r` | `double` | Series resistance (Ω) | +| `x` | `double` | Series reactance (Ω) | +| `g` / `b` | `double` | Magnetizing conductance / susceptance (S) | +| `ratedU1` / `ratedU2` | `double` | Rated voltages at terminals 1 & 2 (kV) | +| `ratedS` | `Double` | Rated nominal apparent power (MVA) | +| `ratioTapChanger` | `RatioTapChangerCreationInfos` | Optional ratio tap changer configuration | +| `phaseTapChanger` | `PhaseTapChangerCreationInfos` | Optional phase tap changer configuration | + +--- + +### 5.5 Injection Modification DTOs + +Injection modification DTOs utilize `AttributeModification` properties for selective, partial updates. + +#### `InjectionModificationInfos` ← `EquipmentModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `voltageLevelId` | `AttributeModification` | Target voltage level | +| `busOrBusbarSectionId` | `AttributeModification` | Target bus / busbar section | + +#### `LoadModificationInfos` ← `InjectionModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `loadType` | `AttributeModification` | Load type | +| `p0` | `AttributeModification` | Active power consumption (MW) | +| `q0` | `AttributeModification` | Reactive power consumption (MVar) | + +#### `GeneratorModificationInfos` ← `InjectionModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `energySource` | `AttributeModification` | Energy source | +| `minP` / `maxP` | `AttributeModification` | Active power boundaries (MW) | +| `ratedS` | `AttributeModification` | Rated apparent power (MVA) | +| `targetP` / `targetQ` / `targetV` | `AttributeModification` | Operational set points | +| `voltageRegulationOn` | `AttributeModification` | Voltage regulation status | +| `participate` | `AttributeModification` | Frequency regulation participation | +| `droop` | `AttributeModification` | Droop coefficient | +| `reactiveCapabilityCurvePoints` | `List` | Capability curve points | + +#### `BatteryModificationInfos` ← `InjectionModificationInfos` + +Mirrors generator modification attributes applicable to battery storage systems. + +#### `ShuntCompensatorModificationInfos` ← `InjectionModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `sectionCount` | `AttributeModification` | Number of active sections | +| `maximumSectionCount` | `AttributeModification` | Maximum section capacity | +| `voltageSetpoint` | `AttributeModification` | Target voltage set point | + +--- + +### 5.6 Branch Modification DTOs + +#### `BranchModificationInfos` ← `EquipmentModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `r` / `x` | `AttributeModification` | Resistance / Reactance | +| `operationalLimitsGroups1` / `2` | `List` | Limit group modifications at terminals 1 & 2 | +| `connected1` / `connected2` | `AttributeModification` | Terminal connection status | + +#### `LineModificationInfos` ← `BranchModificationInfos` + +Adds `g1`, `b1`, `g2`, `b2` wrapped in `AttributeModification`. + +#### `TwoWindingsTransformerModificationInfos` ← `BranchModificationInfos` + +Adds `g`, `b`, `ratedU1`, `ratedU2`, `ratedS`, `ratioTapChanger`, and `phaseTapChanger` attribute modifications. + +--- + +### 5.7 Substation & Voltage Level DTOs + +#### `SubstationCreationInfos` ← `EquipmentCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `country` | `Country` | Country code (ISO 3166-1 alpha-2) | +| `voltageLevels` | `List` | Child voltage levels to instantiate within substation | + +#### `SubstationModificationInfos` ← `EquipmentModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `country` | `AttributeModification` | Updated country code | + +#### `VoltageLevelCreationInfos` ← `EquipmentCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `substationId` | `String` | Parent substation identifier | +| `nominalV` | `double` | Nominal voltage (kV) | +| `lowVoltageLimit` / `highVoltageLimit` | `Double` | Operating voltage limits (kV) | +| `ipMin` / `ipMax` | `Double` | Short-circuit current limits (A) | +| `busbarCount` | `int` | Number of busbars (node-breaker) | +| `sectionCount` | `int` | Section count per busbar | +| `switchKinds` | `List` | Switch types between sections | +| `couplingDevices` | `List` | Initial coupling devices | +| `topologyKind` | `TopologyKind` | `BUS_BREAKER` or `NODE_BREAKER` | + +#### `VoltageLevelModificationInfos` ← `EquipmentModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `nominalV` | `AttributeModification` | Nominal voltage | +| `lowVoltageLimit` / `highVoltageLimit` | `AttributeModification` | Voltage operating limits | +| `ipMin` / `ipMax` | `AttributeModification` | Current limits | + +--- + +### 5.8 HVDC DTOs + +#### `VscCreationInfos` ← `EquipmentCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `dcNominalVoltage` | `double` | DC nominal voltage (kV) | +| `dcResistance` | `double` | DC line resistance (Ω) | +| `nominalV` | `double` | AC nominal voltage (kV) | +| `maxP` | `double` | Maximum active power capacity (MW) | +| `activePowerSetpoint` | `double` | Active power set point (MW) | +| `operatorActivePowerLimitSide1` / `Side2` | `Float` | Operator limits | +| `convertersMode` | `HvdcLine.ConvertersMode` | Converter rectifier/inverter modes | +| `converterStation1` / `converterStation2` | `ConverterStationCreationInfos` | VSC converter station specifications | +| `angleDroopActivePowerControl` | `Boolean` | Enable angle droop control | +| `p0` / `droop` | `Float` | Active power reference and droop slope | + +#### `LccCreationInfos` ← `EquipmentCreationInfos` + +| Field | Type | Description | +|---|---|---| +| `nominalV` / `dcNominalVoltage` / `dcResistance` | `double` | Electrical parameters | +| `maxP` / `activePowerSetpoint` | `double` | Power limits and set points | +| `convertersMode` | `HvdcLine.ConvertersMode` | Converter mode | +| `converterStation1` / `converterStation2` | `LccConverterStationCreationInfos` | LCC converter stations | + +--- + +### 5.9 Topology Modification DTOs + +| DTO Class | Fields | Purpose | +|---|---|---| +| `LineSplitWithVoltageLevelInfos` | `lineToSplitId`, `percent`, `mayNewVoltageLevelInfos`, `existingVoltageLevelId`, `bbsOrBusId`, `newLine1Id`, `newLine2Id`, `newLine1Name`, `newLine2Name` | Split line by inserting a voltage level | +| `LineAttachToVoltageLevelInfos` | `lineToAttachToId`, `percent`, `attachmentPointId`, `attachmentPointName`, `mayNewVoltageLevelInfos`, `existingVoltageLevelId`, `bbsOrBusId`, `attachmentLineId`, `attachmentLineName`, `newLine1Id`, `newLine2Id` | Attach end of line to a voltage level | +| `LinesAttachToSplitLinesInfos` | `lineToAttachTo1Id`, `lineToAttachTo2Id`, `attachedLineId`, `voltageLevelId`, `bbsBusId`, `replacingLine1Id`, `replacingLine1Name`, `replacingLine2Id`, `replacingLine2Name` | Attach lines around a split configuration | +| `DeleteVoltageLevelOnLineInfos` | `lineToAttachTo1Id`, `lineToAttachTo2Id`, `replacingLine1Id`, `replacingLine1Name` | Remove intermediate voltage level from line | +| `DeleteAttachingLineInfos` | `lineToAttachTo1Id`, `lineToAttachTo2Id`, `attachedLineId`, `replacingLine1Id`, `replacingLine1Name` | Delete attaching line | +| `CreateCouplingDeviceInfos` | `voltageLevelId`, `couplingDeviceInfos` | Add coupling breaker between busbars | +| `CreateVoltageLevelTopologyInfos` | `substationId`, `voltageLevelId`, `voltageLevelName`, `nominalV`, `lowVoltageLimit`, `highVoltageLimit`, `busbarCount`, `sectionCount`, `switchKinds` | Create full voltage level topology | +| `CreateVoltageLevelSectionInfos` | `voltageLevelId`, `switchKinds` | Add a section to an existing voltage level | +| `MoveVoltageLevelFeederBaysInfos` | `voltageLevelId`, `feederBaysMoves` | Reallocate bays across busbar sections | +| `VoltageLevelTopologyModificationInfos` | `busbarSectionToSwitchesAttributes` | Update switch topology configuration | + +--- + +### 5.10 Deletion DTOs + +#### `EquipmentDeletionInfos` ← `EquipmentModificationInfos` + +Deletes a single piece of equipment identified by `equipmentId` and `equipmentType`. + +#### `ByFilterDeletionInfos` ← `ModificationInfos` + +Deletes all equipment matching filter criteria. + +| Field | Type | Description | +|---|---|---| +| `equipmentType` | `IdentifiableType` | Target equipment type | +| `filters` | `List` | Filter identifiers used to select equipment | + +--- + +### 5.11 Scaling & Dispatch DTOs + +#### `ScalingInfos` ← `ModificationInfos` + +Abstract base for power scaling. + +| Field | Type | Description | +|---|---|---| +| `variations` | `List` | List of scaling variations | +| `variationType` | `VariationType` | `DELTA_P` (relative delta) or `TARGET_P` (absolute value) | + +- `GeneratorScalingInfos` ← `ScalingInfos` (scales active power across selected generators). +- `LoadScalingInfos` ← `ScalingInfos` (scales active power across selected loads). + +#### `ScalingVariationInfos` + +| Field | Type | Description | +|---|---|---| +| `filters` | `List` | Selection filter definitions | +| `variationMode` | `VariationMode` | `PROPORTIONAL_TO_PMAX`, `PROPORTIONAL_TO_P`, `REGULAR_DISTRIBUTION`, `STACKING_UP`, `VENTILATION` | +| `variationValue` | `double` | Target power variation value (MW) | +| `reactiveVariationMode` | `ReactiveVariationMode` | `CONSTANT_Q` or `TAN_PHI_FIXED` | + +#### `GenerationDispatchInfos` ← `ModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `lossCoefficient` | `double` | Loss percentage factor | +| `defaultOutageRate` | `double` | Generator outage rate default | +| `generatorsWithoutOutage` | `List` | Exempted generators | +| `generatorsWithFixedSupply` | `List` | Fixed supply generators | +| `generatorsFrequencyReserve` | `List` | Frequency reserve allocation | +| `substationsGeneratorsOrdering` | `List` | Dispatch ordering preferences | +| `loadFlowParametersUuid` | `UUID` | Load-flow settings reference | + +--- + +### 5.12 Bulk & Programmatic Modification DTOs + +| DTO Class | Fields | Purpose | +|---|---|---| +| `EquipmentAttributeModificationInfos` | `equipmentAttributeName`, `equipmentAttributeValue`, `equipmentType` | Modify a specific attribute by name | +| `GroovyScriptInfos` | `script` | Execute dynamic Groovy script on `network` | +| `TabularModificationInfos` | `modificationType`, `modifications` | Batch modify multiple equipment from a table | +| `TabularCreationInfos` | `creationType`, `creations` | Batch create multiple equipment from a table | +| `LimitSetsTabularModificationInfos` | Inherits `TabularModificationInfos` | Bulk edit operational limit sets | +| `ByFormulaModificationInfos` | `identifiableType`, `formulaInfosList` | Calculate attribute values via mathematical expressions | +| `ModificationByAssignmentInfos` | `identifiableType`, `assignmentInfosList` | Assign values based on filter conditions | + +--- + +### 5.13 Operational Modification DTOs + +#### `OperatingStatusModificationInfos` ← `EquipmentModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `energizedVoltageLevelId` | `String` | Voltage level providing energization | +| `action` | `ActionType` | `LOCKOUT`, `TRIP`, `SWITCH_ON`, `ENERGISE_END_ONE`, `ENERGISE_END_TWO` | + +#### `BalancesAdjustmentModificationInfos` ← `ModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `areas` | `List` | Area exchange targets | +| `loadFlowParametersUuid` | `UUID` | Load-flow settings reference | + +#### `VoltageInitModificationInfos` ← `ModificationInfos` + +Contains collections of voltage initialization targets for `generators`, `transformers`, `staticVarCompensators`, `vscConverterStations`, `shuntCompensators`, and `buses`. + +--- + +### 5.14 Composition & Reference DTOs + +#### `CompositeModificationInfos` ← `ModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `name` | `String` | Descriptive scenario/composite name | +| `modificationsInfos` | `List` | Ordered list of child modifications | +| `maxDepth` | `Integer` | Computed maximum nesting depth | + +#### `ModificationReferenceInfos` ← `ModificationInfos` + +| Field | Type | Description | +|---|---|---| +| `referenceId` | `UUID` | UUID of the referenced modification | +| `referenceType` | `Type` | `BASIC` or `DIRECTORY` | +| `referenceInfos` | `ModificationInfos` | Resolved DTO representation | + +--- + +## 6. Supporting Value Objects + +### `AttributeModification` + +Generic container for partial update operations: + +```java +// Explicit update +AttributeModification setP = new AttributeModification<>(250.0, OperationType.SET); + +// Reset to default +AttributeModification unsetP = new AttributeModification<>(null, OperationType.UNSET); + +// Helper factory +AttributeModification modP = AttributeModification.toAttributeModification(250.0, OperationType.SET); +``` + +### `FilterInfos` + +Carries `UUID id` and `String name` for referencing filter rules. + +### `CurrentLimitsInfos` + +Carries `Double permanentLimit` and `List temporaryLimits`. + +### `FreePropertyInfos` + +Carries `String name`, `String value`, and `boolean deletionMark` for arbitrary equipment metadata tags. + +--- + +## 7. Exceptions & Error Types + +**Package:** `org.gridsuite.modification.error` + +`NetworkModificationException` extends `com.powsybl.commons.PowsyblException` and encapsulates domain-level errors encountered during check or apply phases. + +### Error Types (`NetworkModificationExceptionType`) + +| Type | Default Message | +|---|---| +| `GROOVY_SCRIPT_EMPTY` | The groovy script is empty | +| `LINE_NOT_FOUND` | The line could not be found | +| `LOAD_NOT_FOUND` | The load could not be found | +| `BATTERY_NOT_FOUND` | The battery could not be found | +| `GENERATOR_NOT_FOUND` | The generator could not be found | +| `TWO_WINDINGS_TRANSFORMER_NOT_FOUND` | The two windings transformer could not be found | +| `UNKNOWN_EQUIPMENT_TYPE` | The equipment type is unknown | +| `WRONG_EQUIPMENT_TYPE` | The equipment type does not match the expected type | +| `MODIFICATION_ERROR` | An error occurred while applying the modification | +| `VOLTAGE_LEVEL_NOT_FOUND` | The voltage level could not be found | +| `BUSBAR_SECTION_NOT_FOUND` | The busbar section could not be found | +| `BUS_NOT_FOUND` | The bus could not be found | +| `CREATE_BATTERY_ERROR` | An error occurred while creating the battery | +| `CREATE_GENERATOR_ERROR` | An error occurred while creating the generator | +| `CREATE_SHUNT_COMPENSATOR_ERROR` | An error occurred while creating the shunt compensator | +| `MODIFY_SHUNT_COMPENSATOR_ERROR` | An error occurred while modifying the shunt compensator | +| `CREATE_STATIC_VAR_COMPENSATOR_ERROR` | An error occurred while creating the static var compensator | +| `EQUIPMENT_NOT_FOUND` | The equipment could not be found | +| `ATTRIBUTE_NOT_EDITABLE` | The equipment attribute is not editable | +| `CREATE_LINE_ERROR` | An error occurred while creating the line | +| `MODIFY_LINE_ERROR` | An error occurred while modifying the line | +| `CREATE_TWO_WINDINGS_TRANSFORMER_ERROR` | An error occurred while creating the two windings transformer | +| `MODIFY_TWO_WINDINGS_TRANSFORMER_ERROR` | An error occurred while modifying the two windings transformer | +| `CREATE_VOLTAGE_LEVEL_ERROR` | An error occurred while creating the voltage level | +| `MODIFY_VOLTAGE_LEVEL_ERROR` | An error occurred while modifying the voltage level | +| `SUBSTATION_NOT_FOUND` | The substation could not be found | +| `BATTERY_ALREADY_EXISTS` | A battery with this identifier already exists | +| `LOAD_ALREADY_EXISTS` | A load with this identifier already exists | +| `VOLTAGE_LEVEL_ALREADY_EXISTS` | A voltage level with this identifier already exists | +| `GENERATOR_ALREADY_EXISTS` | A generator with this identifier already exists | +| `SHUNT_COMPENSATOR_ALREADY_EXISTS` | A shunt compensator with this identifier already exists | +| `SHUNT_COMPENSATOR_NOT_FOUND` | The shunt compensator could not be found | +| `STATIC_VAR_COMPENSATOR_ALREADY_EXISTS` | A static var compensator with this identifier already exists | +| `STATIC_VAR_COMPENSATOR_NOT_FOUND` | The static var compensator could not be found | +| `LINE_ALREADY_EXISTS` | A line with this identifier already exists | +| `TWO_WINDINGS_TRANSFORMER_ALREADY_EXISTS` | A two windings transformer with this identifier already exists | +| `TWO_WINDINGS_TRANSFORMER_CREATION_ERROR` | An error occurred while creating the two windings transformer | +| `BRANCH_MODIFICATION_ERROR` | An error occurred while modifying the branch | +| `INJECTION_MODIFICATION_ERROR` | An error occurred while modifying the injection | +| `MODIFY_BATTERY_ERROR` | An error occurred while modifying the battery | +| `OPERATING_STATUS_MODIFICATION_ERROR` | An error occurred while modifying the operating status | +| `OPERATING_ACTION_TYPE_EMPTY` | The operating action type is empty | +| `OPERATING_ACTION_TYPE_UNSUPPORTED` | The operating action type is not supported | +| `EQUIPMENT_TYPE_UNSUPPORTED` | The equipment type is not supported | +| `MODIFY_GENERATOR_ERROR` | An error occurred while modifying the generator | +| `EQUIPMENT_ATTRIBUTE_NAME_ERROR` | The equipment attribute name is invalid | +| `EQUIPMENT_ATTRIBUTE_VALUE_ERROR` | The equipment attribute value is invalid | +| `GENERATOR_SCALING_ERROR` | An error occurred while scaling the generators | +| `LOAD_SCALING_ERROR` | An error occurred while scaling the loads | +| `GENERATION_DISPATCH_ERROR` | An error occurred while dispatching the generation | +| `VOLTAGE_INIT_MODIFICATION_ERROR` | An error occurred while applying the voltage init modification | +| `TABULAR_MODIFICATION_ERROR` | An error occurred while applying the tabular modification | +| `TABULAR_CREATION_ERROR` | An error occurred while applying the tabular creation | +| `CREATE_VSC_ERROR` | An error occurred while creating the VSC converter station | +| `MODIFY_VSC_ERROR` | An error occurred while modifying the VSC converter station | +| `CREATE_LCC_ERROR` | An error occurred while creating the LCC converter station | +| `MODIFY_LCC_ERROR` | An error occurred while modifying the LCC converter station | +| `HVDC_LINE_ALREADY_EXISTS` | An HVDC line with this identifier already exists | +| `VSC_CONVERTER_STATION_NOT_FOUND` | The VSC converter station could not be found | +| `LCC_CONVERTER_STATION_NOT_FOUND` | The LCC converter station could not be found | +| `BY_FORMULA_MODIFICATION_ERROR` | An error occurred while applying the modification by formula | +| `MODIFICATION_BY_ASSIGNMENT_ERROR` | An error occurred while applying the modification by assignment | +| `HVDC_LINE_NOT_FOUND` | The HVDC line could not be found | +| `WRONG_HVDC_ANGLE_DROOP_ACTIVE_POWER_CONTROL` | The HVDC angle droop active power control configuration is invalid | +| `UNSUPPORTED_HYBRID_HVDC` | The hybrid HVDC line is not supported | +| `MODIFY_VOLTAGE_LEVEL_TOPOLOGY_ERROR` | An error occurred while modifying the voltage level topology | +| `CREATE_VOLTAGE_LEVEL_TOPOLOGY_ERROR` | An error occurred while creating the voltage level topology | +| `MOVE_VOLTAGE_LEVEL_FEEDER_BAYS_ERROR` | An error occurred while moving the voltage level feeder bays | + +--- + +## 8. Enumerations Reference + +### `OperationType` + +`SET` (apply new value), `UNSET` (reset to default/null). + +### `VariationType` + +`DELTA_P` (relative change), `TARGET_P` (absolute value). + +### `VariationMode` + +`PROPORTIONAL_TO_PMAX`, `PROPORTIONAL_TO_P`, `REGULAR_DISTRIBUTION`, `STACKING_UP`, `VENTILATION`. + +### `ReactiveVariationMode` + +`CONSTANT_Q` (keep Q constant), `TAN_PHI_FIXED` (keep power factor fixed). + +### `TapChangerType` + +`RATIO`, `PHASE`. + +### `ShuntCompensatorType` + +`CAPACITOR`, `REACTOR`. + +### `VoltageRegulationType` + +`LOCAL`, `DISTANT`. + +### `RegulationSide` + +`SIDE_1`, `SIDE_2`. + +### `OperatingStatusModificationInfos.ActionType` + +`LOCKOUT`, `TRIP`, `SWITCH_ON`, `ENERGISE_END_ONE`, `ENERGISE_END_TWO`. + +--- + +## 9. Usage Examples + +### Example 1 — Create a Load + +```java +LoadCreationInfos loadInfos = LoadCreationInfos.builder() + .equipmentId("LOAD_1") + .equipmentName("Industrial Load 1") + .voltageLevelId("VL_NORTH_400") + .busOrBusbarSectionId("BUS_1") + .loadType(LoadType.UNDEFINED) + .p0(120.0) + .q0(30.0) + .build(); + +loadInfos.check(); +AbstractModification modification = loadInfos.toModification(); +modification.check(network); + +ReportNode reportNode = ReportNode.newRootReportNode() + .withMessageTemplate("root", "Root Report") + .build(); + +modification.apply(network, reportNode); +``` + +### Example 2 — Partial Generator Modification + +```java +GeneratorModificationInfos genModif = GeneratorModificationInfos.builder() + .equipmentId("GEN_HYDRO_1") + .targetP(AttributeModification.toAttributeModification(280.0, OperationType.SET)) + .voltageRegulationOn(AttributeModification.toAttributeModification(true, OperationType.SET)) + .build(); + +genModif.toModification().apply(network, reportNode); +``` + +### Example 3 — Filter-Based Equipment Deletion + +```java +ByFilterDeletionInfos deletion = ByFilterDeletionInfos.builder() + .equipmentType(IdentifiableType.LOAD) + .filters(List.of(new FilterInfos(filterUuid, "Decommissioned Loads"))) + .build(); + +AbstractModification mod = deletion.toModification(); +mod.initApplicationContext(filterService, null); +mod.check(network); +mod.apply(network, reportNode); +``` + +### Example 4 — Composite Scenario Execution + +```java +CompositeModificationInfos scenario = CompositeModificationInfos.builder() + .name("Peak Load Scenario") + .modificationsInfos(List.of(loadInfos, genModif)) + .build(); + +AbstractModification compositeMod = scenario.toModification(); +compositeMod.initApplicationContext(filterService, loadFlowService); +compositeMod.check(network); +compositeMod.apply(network, reportNode); +``` + +### Example 5 — Polymorphic JSON Deserialization + +```json +[ + { + "type": "LOAD_CREATION", + "equipmentId": "LOAD_NEW", + "voltageLevelId": "VL1", + "busOrBusbarSectionId": "BUS1", + "p0": 45.0, + "q0": 12.0 + }, + { + "type": "GENERATOR_MODIFICATION", + "equipmentId": "GEN1", + "targetP": { + "value": 310.0, + "op": "SET" + } + } +] +``` + +```java +ObjectMapper mapper = new ObjectMapper(); +List modifications = mapper.readValue( + jsonString, + mapper.getTypeFactory().constructCollectionType(List.class, ModificationInfos.class) +); +``` + +--- + +*Documentation for `gridsuite-network-modification` — © RTE (http://www.rte-france.com) — MPL-2.0* diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 00000000..ee8e7e91 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,325 @@ +# Architecture Documentation — `gridsuite-network-modification` + +## Overview + +`gridsuite-network-modification` is a Java library designed to apply structural, operational, and topological modifications to electrical power networks. It is part of the [GridSuite](http://www.gridsuite.org/) platform and is built on top of [PowSyBl](https://www.powsybl.org/) (Power System Blocks), an open-source framework for power-system simulation and analysis. + +The library provides a clean, extensible architectural separation between: + +- **Data Transfer Objects (DTOs)** — plain Java models describing *what* network modifications to perform (inputs, configurations, metadata). +- **Modification Implementations** — business logic execution classes that validate and apply mutations to a live PowSyBl `Network` instance. +- **Reporting and Auditing** — integrated internationalized reporting via PowSyBl `ReportNode`. +- **Error Handling** — a unified exception hierarchy mapping power-system modification errors. + +It is intended to be consumed as a library by backend services (such as GridSuite microservices) or standalone Java applications that require programmatic network manipulation. + +--- + +## Technology Stack + +| Concern | Technology | Notes | +|---|---|---| +| Language | Java 25 | Configured in `pom.xml` | +| Build tool | Apache Maven | Parent POM: `powsybl-parent` | +| Core Framework | PowSyBl (`powsybl-iidm-api`, `powsybl-iidm-modification`, `powsybl-loadflow-api`, `powsybl-open-loadflow`, `powsybl-balances-adjustment`) | Network modeling and simulation | +| Filter Framework | `gridsuite-filter` | Equipment filtering engine | +| Serialization & Schema | Jackson (`jackson-databind`, `jackson-datatype-jsr310`), Swagger/OpenAPI v3 annotations | Polymorphic JSON serialization | +| Boilerplate Reduction | Project Lombok | Builder, Getter, Setter, EqualsAndHashCode | +| Scripting Engine | Apache Groovy | Dynamic script-based network modifications | +| Validation | Jakarta Validation API (`jakarta.validation-api`) | Constraint validation | +| Reporting & i18n | PowSyBl `ReportNode`, Java `ResourceBundle` (`AutoService`) | Multi-language execution reports | +| Testing | JUnit 5, Spring Boot Test, PowSyBl Config Test, JaCoCo | Unit and integration testing | + +--- + +## High-Level Module Layout + +``` +org.gridsuite.modification +├── dto/ # Data Transfer Objects (deserialization, models) +│ ├── byfilter/ # DTOs for filter-based modifications +│ │ ├── assignment/ # Assignment descriptors (String, Double, Boolean, Enum) +│ │ ├── equipmentfield/ # Field resolution enums per equipment type +│ │ └── formula/ # Formula-based modification descriptors and operators +│ └── tabular/ # DTOs for tabular / bulk modifications +├── error/ # Unified exception hierarchy and exception types +├── modifications/ # Concrete modification business logic implementations +│ ├── byfilter/ # Filter-based modification execution logic +│ └── tabular/ # Tabular and limit-set bulk modification execution logic +├── report/ # i18n report resource bundle registration (SPI) +├── utils/ # Utility classes (limits, measurements, properties, load-flow) +├── IFilterService.java # Service interface: filter resolution against networks +├── ILoadFlowService.java # Service interface: load-flow parameter retrieval +├── ModificationType.java # Enumeration of all supported modification types +├── ReactiveVariationMode.java # Scaling reactive variation mode enum +├── TapChangerType.java # Tap changer types enum +├── VariationMode.java # Scaling active variation mode enum +└── VariationType.java # Scaling variation type (delta / target) enum +``` + +--- + +## Core Abstractions + +### 1. `AbstractModification` (Modifications Layer) + +``` +com.powsybl.iidm.modification.AbstractNetworkModification + └── AbstractModification (org.gridsuite.modification.modifications) + └── +``` + +Every modification implementation inherits from `AbstractModification`, which extends PowSyBl's `AbstractNetworkModification`. It defines the core execution lifecycle: + +| Method | Purpose | +|---|---| +| `void check(Network network)` | Pre-execution validation against a live `Network` instance. Throws `NetworkModificationException` on validation failure. Default implementation performs no check. | +| `void initApplicationContext(IFilterService filterService, ILoadFlowService loadFlowService)` | Injects external services (e.g., filter resolution or load-flow parameter store). Default implementation does nothing. | +| `void apply(Network network, ReportNode subReportNode)` | Executes the modification logic, mutating the `Network` and writing structured events to the provided `ReportNode`. Must be implemented by subclasses. | +| `void apply(Network network, NamingStrategy namingStrategy, ReportNode subReportNode)` | Variant accepting an explicit `NamingStrategy`. Delegates by default to `apply(network, subReportNode)`. | +| `String getName()` | Returns a stable, human-readable name identifying the modification type. | + +### 2. `ModificationInfos` (DTO Layer) + +`ModificationInfos` is the abstract base class for all modification Data Transfer Objects. It supports polymorphic JSON serialization and deserialization using Jackson annotations (`@JsonTypeInfo` and `@JsonSubTypes`) with the `type` property as discriminator. + +Key properties: + +| Property | Type | Description | +|---|---|---| +| `uuid` | `UUID` | Unique identifier of the modification instance | +| `type` | `ModificationType` | Automatically derived from the class `@JsonTypeName` or explicitly set | +| `date` | `Instant` | Timestamp of creation or modification | +| `stashed` | `Boolean` | Staging flag; stashed modifications (`true`) are skipped during execution | +| `activated` | `Boolean` | Activation flag; deactivated modifications are skipped during execution | +| `description` | `String` | Optional user description or scenario notes | +| `messageType` | `String` | i18n message key template | +| `messageValues` | `String` | Serialized message interpolation parameters | + +Key methods: + +| Method | Description | +|---|---| +| `AbstractModification toModification()` | Factory method that instantiates the corresponding `AbstractModification` implementation. | +| `ReportNode createSubReportNode(ReportNode reportNode)` | Creates and attaches a child `ReportNode` with the appropriate message template for this modification. | +| `void check()` | Validates internal DTO fields before converting to an executable modification. | +| `ModificationType getType()` | Returns the resolved `ModificationType` enum value. | +| `Map getMapMessageValues()` | Returns interpolation parameters as key-value pairs for reporting. | + +### 3. DTO Inheritance Hierarchy + +``` +ModificationInfos +├── EquipmentModificationInfos # Base for modifications targeting single equipment (equipmentId, properties) +│ ├── BasicEquipmentModificationInfos # Lightweight property/attribute modification +│ ├── EquipmentCreationInfos # Base for creating new equipment (+ equipmentName) +│ │ ├── InjectionCreationInfos # Injections (voltageLevelId, busOrBusbarSectionId, feeder bay) +│ │ │ ├── LoadCreationInfos # Load creation +│ │ │ ├── GeneratorCreationInfos # Generator creation (active/reactive limits, regulation) +│ │ │ ├── BatteryCreationInfos # Battery storage creation +│ │ │ ├── ShuntCompensatorCreationInfos # Capacitor / reactor creation +│ │ │ └── StaticVarCompensatorCreationInfos # SVC creation +│ │ ├── BranchCreationInfos # Branches (terminals 1 & 2, limits, connection states) +│ │ │ ├── LineCreationInfos # AC transmission line creation +│ │ │ └── TwoWindingsTransformerCreationInfos# Two-windings power transformer creation +│ │ ├── SubstationCreationInfos # Substation creation with nested voltage levels +│ │ ├── VoltageLevelCreationInfos # Voltage level creation (topology kind, busbars, switches) +│ │ ├── VscCreationInfos # VSC HVDC line creation +│ │ ├── LccCreationInfos # LCC HVDC line creation +│ │ ├── ConverterStationCreationInfos # VSC converter station creation +│ │ └── LccConverterStationCreationInfos # LCC converter station creation +│ ├── InjectionModificationInfos # Attribute modifications for injections (partial updates) +│ │ ├── LoadModificationInfos # Load parameter updates +│ │ ├── GeneratorModificationInfos # Generator parameter updates +│ │ ├── BatteryModificationInfos # Battery parameter updates +│ │ └── ShuntCompensatorModificationInfos # Shunt compensator updates +│ ├── BranchModificationInfos # Attribute modifications for branches +│ │ ├── LineModificationInfos # Line parameter updates +│ │ └── TwoWindingsTransformerModificationInfos# Transformer parameter updates +│ ├── SubstationModificationInfos # Substation attribute updates +│ ├── VoltageLevelModificationInfos # Voltage level attribute updates +│ ├── VscModificationInfos / LccModificationInfos# HVDC parameter updates +│ ├── ConverterStationModificationInfos # VSC converter station updates +│ ├── LccConverterStationModificationInfos # LCC converter station updates +│ ├── EquipmentDeletionInfos # Equipment deletion by ID and type +│ ├── EquipmentAttributeModificationInfos # Single attribute modification by name +│ ├── OperatingStatusModificationInfos # Operational status changes (lockout, trip, switch on) +│ └── VoltageLevelTopologyModificationInfos # Busbar/switch configuration within a voltage level +├── CompositeModificationInfos # Ordered sequence of sub-modifications +├── ModificationReferenceInfos # Delegation to a modification by UUID +├── GeneratorScalingInfos / LoadScalingInfos # Power scaling across equipment groups +├── GenerationDispatchInfos # Generation dispatch with loss & outage optimization +├── BalancesAdjustmentModificationInfos # Area net position balances adjustment +├── VoltageInitModificationInfos # Voltage initialization across buses and generators +├── GroovyScriptInfos # Direct Groovy script execution on Network +├── TabularModificationInfos / TabularCreationInfos # Bulk tabular modifications and creations +├── LimitSetsTabularModificationInfos # Bulk operational limit sets modifications +├── ByFormulaModificationInfos # Dynamic formula-based attribute calculations +├── ModificationByAssignmentInfos # Value assignment based on filter conditions +├── ByFilterDeletionInfos # Bulk equipment deletion matching filter criteria +└── Topology Modifications # Line splits, line attachments, feeder bay moves, coupling devices +``` + +--- + +## Modification Categories + +### 1. Equipment Creation & Modification (CRUD) + +Direct lifecycle operations on individual power system network elements: + +- **Injections**: Loads, Generators, Battery storage, Shunt compensators (capacitors/reactors), Static Var Compensators (SVC). +- **Branches**: AC Lines, Two-Windings Transformers (with ratio and phase tap changers). +- **Substations & Topology**: Substations, Voltage levels (Bus-Breaker and Node-Breaker topologies). +- **HVDC Systems**: VSC (Voltage Source Converter) and LCC (Line-Commutated Converter) lines and converter stations. + +### 2. Equipment Deletion + +- `EQUIPMENT_DELETION`: Deletes an individual equipment item specified by ID and type. +- `BY_FILTER_DELETION`: Resolves filters via `IFilterService` and deletes all matched equipment from the network. + +### 3. Topology Modifications + +Complex topological and structural rewiring operations: + +- `LINE_SPLIT_WITH_VOLTAGE_LEVEL`: Splits a transmission line by inserting a new or existing voltage level. +- `LINE_ATTACH_TO_VOLTAGE_LEVEL`: Attaches an end of a line to an existing or new voltage level. +- `LINES_ATTACH_TO_SPLIT_LINES`: Reconnects existing lines to split line segments. +- `DELETE_VOLTAGE_LEVEL_ON_LINE`: Removes an intermediate voltage level and merges the line segments. +- `DELETE_ATTACHING_LINE`: Deletes an attaching line and restores original topology. +- `CREATE_COUPLING_DEVICE`: Creates a busbar coupling breaker/switch between busbar sections. +- `CREATE_VOLTAGE_LEVEL_TOPOLOGY`: Builds complete bus-breaker or node-breaker topology arrangements. +- `CREATE_VOLTAGE_LEVEL_SECTION`: Adds a new busbar section to a voltage level. +- `MOVE_VOLTAGE_LEVEL_FEEDER_BAYS`: Reorganizes feeder bay connections across busbar sections. + +### 4. Bulk & Programmatic Modifications + +- `TABULAR_MODIFICATION` & `TABULAR_CREATION`: Executes batch attribute edits or equipment creations from tabular datasets. +- `LIMIT_SETS_TABULAR_MODIFICATION`: Bulk configuration of temporary and permanent operational limit sets. +- `BY_FORMULA_MODIFICATION`: Computes attribute values dynamically using mathematical formulas and equipment references. +- `MODIFICATION_BY_ASSIGNMENT`: Assigns values conditionally (String, Double, Boolean, Enum) to equipment matching filters. +- `EQUIPMENT_ATTRIBUTE_MODIFICATION`: Dynamically modifies a named property/attribute on target equipment. +- `GROOVY_SCRIPT`: Executes an arbitrary Groovy script against the `network` context for custom algorithms. + +### 5. Operational & Power-Flow Adjustments + +- `OPERATING_STATUS_MODIFICATION`: Switches equipment status (`LOCKOUT`, `TRIP`, `SWITCH_ON`, `ENERGISE_END_ONE`, `ENERGISE_END_TWO`). +- `GENERATOR_SCALING` & `LOAD_SCALING`: Proportional, stacked, or regular power scaling with active/reactive management. +- `GENERATION_DISPATCH`: Solves power dispatch to meet target balance considering outage rates and frequency reserves. +- `BALANCES_ADJUSTMENT_MODIFICATION`: Balances area exchanges and net positions using PowSyBl Balances Adjustment. +- `VOLTAGE_INIT_MODIFICATION`: Initializes network voltage profile (bus voltages, generator targets, transformer taps). + +### 6. Composition & Orchestration + +- `COMPOSITE_MODIFICATION`: Executes an ordered list of sub-modifications. Handles nested execution and isolates errors so failure of one modification does not abort the entire sequence unless desired. +- `MODIFICATION_REFERENCE`: Resolves and executes a modification defined externally and referenced by UUID. + +--- + +## Key Design Patterns + +### 1. DTO ↔ Implementation Factory Pattern + +Each concrete DTO overrides `toModification()` to instantiate its matching `AbstractModification` implementation. This preserves separation between network data representation (serializable DTOs) and business logic execution: + +```java +// DTO layer +public AbstractModification toModification() { + return new GeneratorCreation(this); +} + +// Caller execution workflow +ModificationInfos dto = ...; +dto.check(); // DTO validation +AbstractModification modification = dto.toModification(); +modification.initApplicationContext(filterService, loadFlowService); +modification.check(network); // Domain validation +modification.apply(network, reportNode); // Network mutation +``` + +### 2. Partial Updates via `AttributeModification` + +To support partial updates where unspecified properties remain untouched, modification DTOs wrap mutable fields in `AttributeModification`: + +- **Field is `null`**: Property is omitted; current network value is preserved. +- **`OperationType.SET`**: Property is explicitly updated to the new value. +- **`OperationType.UNSET`**: Property is reset to its default or null value. + +### 3. Polymorphic Serialization + +Jackson's `@JsonTypeInfo` and `@JsonSubTypes` enable transparent serialization and deserialization of heterogeneous collections of modification descriptors via standard REST APIs and JSON files without custom parsing logic. + +### 4. Hierarchical Reporting + +All modifications log execution events, warnings, and messages through PowSyBl's `ReportNode` hierarchy. A dedicated SPI resource bundle (`NetworkModificationReportResourceBundle`) registers message templates in multiple languages (English, French). + +### 5. Service Abstraction + +Modifications requiring external infrastructure rely on interfaces: +- `IFilterService`: Decouples filter evaluation and remote filter microservices from the modification core. +- `ILoadFlowService`: Decouples load-flow parameter storage from power-flow-based modifications. + +--- + +## Error Handling Architecture + +All domain errors produce a `NetworkModificationException` (inheriting from PowSyBl's `PowsyblException`). + +- Each exception carries a `NetworkModificationExceptionType` enum value providing a descriptive message and clear error classification. +- Static factory methods on `NetworkModificationException` provide standard error construction: + - `createEquipmentTypeUnknown(type)` + - `createEquipmentTypeNotSupported(type)` + - `createOperatingActionTypeUnsupported(actionType)` + - `createEquipementAttributeNotEditable(equipmentType, attributeName)` + - `createHybridHvdcUnsupported(hvdcId)` + +--- + +## Data Flow + +``` +Consumer Application / Service + │ + │ 1. Deserialise JSON / construct DTO + ▼ + ModificationInfos.check() ← Validates DTO consistency + │ + │ 2. Convert to executable modification + ▼ + ModificationInfos.toModification() → AbstractModification + │ + │ 3. Inject external services (optional) + ▼ + AbstractModification.initApplicationContext(filterService, loadFlowService) + │ + │ 4. Validate against target network + ▼ + AbstractModification.check(network) ← Throws NetworkModificationException on conflict + │ + │ 5. Mutate network and record reporting + ▼ + AbstractModification.apply(network, reportNode) + │ + ▼ + Mutated PowSyBl Network + Populated ReportNode Tree +``` + +--- + +## Package Summary + +| Package | Description | +|---|---| +| `org.gridsuite.modification` | Root package: core interfaces (`IFilterService`, `ILoadFlowService`), enums (`ModificationType`, `VariationType`, `VariationMode`, `ReactiveVariationMode`, `TapChangerType`) | +| `org.gridsuite.modification.dto` | Core modification DTOs (CRUD, topology, scaling, dispatch, operational, references) | +| `org.gridsuite.modification.dto.byfilter` | Filter-based modification DTOs | +| `org.gridsuite.modification.dto.byfilter.assignment` | Assignment descriptors for typed modifications (String, Double, Boolean, Enum) | +| `org.gridsuite.modification.dto.byfilter.equipmentfield` | Equipment attribute target field enums | +| `org.gridsuite.modification.dto.byfilter.formula` | Mathematical formula descriptors and operator enums | +| `org.gridsuite.modification.dto.tabular` | Tabular batch modifications and limit set DTOs | +| `org.gridsuite.modification.error` | `NetworkModificationException` and `NetworkModificationExceptionType` | +| `org.gridsuite.modification.modifications` | Executable modification logic classes | +| `org.gridsuite.modification.modifications.byfilter` | Filter-based and formula-based execution classes | +| `org.gridsuite.modification.modifications.tabular` | Tabular batch execution classes | +| `org.gridsuite.modification.report` | Internationalized report bundle SPI (`NetworkModificationReportResourceBundle`) | +| `org.gridsuite.modification.utils` | Shared utility classes (limits, measurements, properties, load-flow configuration) |