diff --git a/doc/4_Interoperability/3_hybrid.md b/doc/4_Interoperability/3_hybrid.md
index 942adace..1b927b89 100644
--- a/doc/4_Interoperability/3_hybrid.md
+++ b/doc/4_Interoperability/3_hybrid.md
@@ -43,40 +43,139 @@ The following steps describe how to **link the GEMS part of the study to the Leg
### Abstract definition of the area-connection field type (in the [library](../3_User_Guide/3_GEMS_File_Structure/2_library.md) file)
-In order to successfully inject a GEMS component’s port into an Antares Legacy Area, the port’s type must declare which field represents the power injection. This is configured in the [library](../3_User_Guide/3_GEMS_File_Structure/2_library.md) of the component's model (e.g., a file `model-libraries/library.yml`). Within the port type definition, an `area-connection` section specifies an `injection-field`. The `injection-field` designates which field of that port will be added to the connected area’s balance equation. For example, for a port type that carries power `flow`, it is defined in the library as follows:
+In order to successfully inject a GEMS component’s port into an Antares Legacy Area, the port’s type must declare which field will contribute to the optimization problem. This is configured in the [library](../3_User_Guide/3_GEMS_File_Structure/2_library.md) of the component's model (e.g. a file `model-libraries/library.yml`).
+
+The `area-connection` section is optional in general, but becomes mandatory when the port type is intended to be used in a **hybrid study**. It can accept 3 types of fields `injection-to-balance`, `spillage-bound` and `unsupplied-energy-bound` :
```yaml
- port-types:
- - id: flow
- description: A port that transfers a power flow.
- fields:
- - id: flow
- area-connection:
- - injection-field: flow
+port-types:
+ - id: port-to-area
+ fields:
+ - id: field_to_balance
+ - id: to-area-bound
+ - id: from-area-bound
+ area-connection:
+ injection-to-balance: field_to_balance
+ spillage-bound: to-area-bound
+ unsupplied-energy-bound: from-area-bound
```
-The `area-connection` section is optional in general, but becomes mandatory when the port type is intended to be used in a **hybrid study**.
+The nature of the contribution depends on the fields:
+
+- `injection-to-balance`: the linear expression is injected in the balance constraint of the area.
+- `spillage-bound`: the linear expression is added to the sum of all variables or linear expressions already used to bound the spillage in the constraint called "fictitious load".
+- `unsupplied-energy-bound`: the linear expression is added to any linear expression already used to bound the unsupplied energy.
+
+These fields are independent: you don't have to define all 3 at the same time, you can define only one. However, all three keys must be present in the `area-connection` section even if some values are left empty.
+
+#### Single field case
+
+It's not mandatory to connect one field for each `area-connection` entry, it's possible to define only one of them. For example, for a port type that carries power `flow_field` and only connects to the balance constraint, it is defined in the library as follows:
+
+```yaml
+port-types:
+ - id: flow_port
+ description: A port that transfers a power flow.
+ fields:
+ - id: flow_field
+ area-connection:
+ injection-to-balance: flow_field
+ spillage-bound:
+ unsupplied-energy-bound:
+
+models:
+ - id: my-production
+ parameters:
+ - id: flat_production
+ ports:
+ - id: balance_port
+ type: flow_port
+ port-field-definitions:
+ - port: balance_port
+ field: flow_field
+ definition: flat_production
+```
+
+### Conventions on the sign of expressions
+
+When connecting a component to an area, you must respect conventions on the sign of the linear expression contributed by the port field.
+
+
+
+
+Sign conventions for the injection-to-balance
+
+
+ - If you need to involve a production, make the expression positive (no
- prefix):
+port-field-definitions:
+ - port: balance_port
+ field: flow_field
+ definition: flat_production # positive production
+
+
+ - If you need to involve a load, make the expression negative (prefix with
-):
+port-field-definitions:
+ - port: balance_port
+ field: flow_field
+ definition: -flat_load # negative load
+
+
+
+
+
+
+
+Sign conventions for the spillage-bound
+
+This connection is intended to limit the spillage optimization variable. The convention is the same as for the balance constraint: make the production positive, with no - prefix:
+
+port-field-definitions:
+ - port: spillage_port
+ field: to-area-bound
+ definition: flat_production # positive production
+
+
+
+
+
+Sign conventions for the unsupplied-energy-bound
-The `injection-field` explicitly designates which field of the port contributes to the area balance equation in the legacy Antares Simulator study.
+This connection is intended to limit the unsupplied energy optimization variable. Here, make the load positive, with no - prefix:
+
+port-field-definitions:
+ - port: unsup_energy_port
+ field: from-area-bound
+ definition: flat_load # positive load
+
+
+
### Definition of the area-connections (in the [system](../3_User_Guide/3_GEMS_File_Structure/3_system.md) file)
The `area-connections` section of the system file is used to declare each connection between a GEMS component and an Antares Legacy Area.
-For every component that should supply or interact with an Antares Area, an entry is added specifying the component, the port through which it connects, and the target area name. The port must support the area injection field type. For example, to connect a component `wind_farm` to a legacy area `area1` through `wind_farm`’s port named `balance_port`, the following configuration is used:
+For every component that should supply or interact with an Antares Area, an entry is added specifying the component, the port through which it connects, and the target area name. The port must belong to a port type that defines an `area-connection` section in the model library. For example, to connect a component `wind_farm` to a legacy area `area1` through `wind_farm`'s port named `balance_port`, the following configuration is used:
```yaml
area-connections:
- - component: wind_farm
- port: balance_port
- area: area1
+ - component: wind_farm
+ port: balance_port
+ area: area1
```
Explanation of fields:
- **component:** Refers to the `id` of the GEMS component to be connected. This `id` must match the one declared in the components section of the `system.yml` file. In this example, it refers to a component named `wind_farm`
-- **port:** Specifies which port on the component is used to establish the connection to the Antares Simulator area. The corresponding port type must include an `area-connection` section in the model library definition, and must specify an `injection-field` that will be used by the solver
-- **area:** Indicates the target Antares Simulator area. The component's output, through the defined port, will contribute to this Antares Simulator area’s balance constraint during simulation.
+- **port:** Specifies which port on the component is used to establish the connection to the Antares Simulator area. The corresponding **port type** must include an `area-connection` section in the model library definition, and must specify at least one of `injection-to-balance`, `spillage-bound` or `unsupplied-energy-bound`
+- **area:** Indicates the target Antares Simulator area. The component's output, through the defined port, will contribute to this Antares Simulator area's balance constraint during simulation
+
+## Outputs
+
+The study will generate two types of output files:
+
+- [**Files similar to Legacy studies**](https://antares-simulator.readthedocs.io/en/latest/user-guide/solver/03-outputs/): outputs corresponding to the optimization results coming from the components created by the Legacy study.
+- [**Simulation tables**](https://antares-simulator.readthedocs.io/en/latest/user-guide/modeler/03-outputs/): specific to modeler's components optimization, in the same output folder as the Legacy outputs. One simulation table for each optimization step (called `simulation_table--optim-nb-X`) will be generated.
+
## How to run a hybrid study
@@ -84,7 +183,7 @@ After setting up the connections as described above, **running a hybrid study**
Once the run starts, it will simulate with the combined model. Results for the GEMS components (e.g., generation output of a custom component) will appear alongside the usual Antares results for areas, provided that output has been configured for those components (the GEMS framework will handle output storage in the study results).
-## Simple example of a hybrid study
+## Simple example of a [hybrid study](https://github.com/AntaresSimulatorTeam/GEMS/tree/main/resources/Documentation_Examples/Hybrid_Study)
This section represents a simple example of a hybrid study that demonstrates how to integrate GEMS models into Antares Simulator. The example can be found in the [resources folder](https://github.com/AntaresSimulatorTeam/GEMS/tree/main/resources/Documentation_Examples) and covers a one-week time horizon.
@@ -104,26 +203,28 @@ library:
id: example_library
port-types:
- - id: flow
+ - id: flow_port
description: A port that transfers a power flow.
fields:
- - id: flow
+ - id: flow_field
area-connection:
- - injection-field: flow
+ injection-to-balance: flow_field
+ spillage-bound:
+ unsupplied-energy-bound:
models:
- id: renewable
parameters:
- - id: generation
- time-dependent: true
- scenario-dependent: true
+ - id: generation
+ time-dependent: true
+ scenario-dependent: true
ports:
- - id: balance_port
- type: flow
+ - id: balance_port
+ type: flow_port
port-field-definitions:
- - port: balance_port
- field: flow
- definition: generation
+ - port: balance_port
+ field: flow_field
+ definition: generation
system.yml :
@@ -133,7 +234,6 @@ system:
id: system
components:
-
- id: wind_farm
model: example_library.renewable
parameters:
@@ -160,11 +260,11 @@ In this specific case, wind generation during the first hour is 20MW and demand
When constructing hybrid studies, the following important constraints should be considered:
-**Time Series Length**:
+**Time Series Length:**
The time series data used in GEMS modeler components (for example, the generation profile of a renewable) must align with the Antares simulation horizon and resolution. In practice, this means the number of time steps and the granularity of GEMS time-dependent inputs should match the solver’s expectations (e.g., 8760 hourly values for a yearly hourly simulation). The hybrid solver will not accept a modeler time series that doesn’t fit the configured simulation timeframe.
-**Integer/Binary Decision Variables**:
+**Integer/Binary Decision Variables:**
If any GEMS component introduces integer or binary decision variables (for instance, a component that has an on/off state or unit commitment logic), Antares must be run in MILP mode. Antares Simulator’s solver has to be set to Mixed-Integer Linear Programming (the unit commitment MILP option) to handle discrete variables. In hybrid mode, the solver will incorporate those binary/integer variables into the optimization, but only if the MILP solver is enabled. If running with continuous (LP) mode while using components that require integer decisions, the simulation will not handle them correctly. Thus, the study’s optimization settings must be configured for MILP (unit commitment) when needed.
**Scenario dependency of Variables**:
diff --git a/doc/assets/.$4_hybrid_study_scheme.drawio.bkp b/doc/assets/.$4_hybrid_study_scheme.drawio.bkp
index 284166ae..0aeeac28 100644
--- a/doc/assets/.$4_hybrid_study_scheme.drawio.bkp
+++ b/doc/assets/.$4_hybrid_study_scheme.drawio.bkp
@@ -1,6 +1,6 @@
-
+
@@ -20,11 +20,11 @@
-
+
-
-
+
+
@@ -43,7 +43,7 @@
-
+
diff --git a/doc/assets/.$4_hybrid_study_scheme.png.bkp b/doc/assets/.$4_hybrid_study_scheme.png.bkp
new file mode 100644
index 00000000..11d981c4
Binary files /dev/null and b/doc/assets/.$4_hybrid_study_scheme.png.bkp differ
diff --git a/doc/assets/4_hybrid_study_scheme.drawio b/doc/assets/4_hybrid_study_scheme.drawio
index 0aeeac28..bf4c4579 100644
--- a/doc/assets/4_hybrid_study_scheme.drawio
+++ b/doc/assets/4_hybrid_study_scheme.drawio
@@ -1,6 +1,6 @@
-
+
-
+
@@ -21,10 +21,10 @@
-
+
-
-
+
+
@@ -42,8 +42,11 @@
-
-
+
+
+
+
+
diff --git a/doc/assets/4_hybrid_study_scheme.png b/doc/assets/4_hybrid_study_scheme.png
index c1996bee..11d981c4 100644
Binary files a/doc/assets/4_hybrid_study_scheme.png and b/doc/assets/4_hybrid_study_scheme.png differ
diff --git a/doc/assets/4_sign_conventions.drawio b/doc/assets/4_sign_conventions.drawio
new file mode 100644
index 00000000..e106f695
--- /dev/null
+++ b/doc/assets/4_sign_conventions.drawio
@@ -0,0 +1,99 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/assets/4_sign_conventions.png b/doc/assets/4_sign_conventions.png
new file mode 100644
index 00000000..b4b93a42
Binary files /dev/null and b/doc/assets/4_sign_conventions.png differ