What's needed?
We need to make the following updates to the Frequenz open-source repository to correctly represent power quantities in MW for electricity trading in spot markets:
- Add a new Power.proto in the common repository to represent power in MW.
- Update electricity_trading.proto to correctly use power (in MW) for quantity in spot market trading, where currently energy (in MWh) is incorrectly specified.
Proposed solution
- Create Power.proto in the common/v1/market/ directory
The new Power.proto file should be created in the common/v1/market/ package. This will represent power in MW. Below is the proposed file structure:
// Frequenz definitions of power.
//
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
//
// Licensed under the MIT License (the "License");
// you may not use this file except in compliance with the License.
syntax = "proto3";
package frequenz.api.common.v1.market;
import "frequenz/api.common.v1.types/decimal.proto";
// Represents a unit of power.
//
// !!! note
// The power unit is denominated in MW (Megawatts), which is a unit of power
// representing the rate of energy production or consumption at any given
// moment. This differs from MWh (Megawatt-hours), which measures the total
// amount of energy delivered or consumed over a period.
//
// Example:
// A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
//
// This message standardizes the representation of power in MW across all
// market applications.
message Power {
// Power amount in Megawatts (MW).
frequenz.api.common.v1.types.Decimal mw = 1;
}
- Update electricity_trading.proto to use
Power for Quantity Representation
We also need to modify the electricity_trading.proto to reflect that spot market trades deal in MW for the quantity, while prices remain in EUR/MWh. The existing Energy field in the Order message should be replaced by Power.
Here is the proposed diff for this update:
// Represents an order in the electricity market.
message Order {
// The quantity of power being traded, specified in MW (Megawatts)
+ //
+ // !!! note
+ // Spot market trades specify power in MW, while prices are quoted in [Currency]/MWh.
+ //
+ // !!! example
+ // For a 15-minute contract:
+ // - If you trade 10 MW of power at a price of 50 [Currency]/MWh, the total power traded is 10 MW.
+ // - The total energy delivered over 15 minutes is:
+ // Energy (MWh) = Power (MW) * Time (hours) = 10 MW * 0.25 hours = 2.5 MWh.
+ // - The total cost for this 15-minute trade is:
+ // Total Cost = Energy (MWh) * Price ([Currency]/MWh) = 2.5 MWh * 50 [Currency]/MWh = 125 [Currency].
- frequenz.api.common.v1.market.Energy quantity = 7;
+ frequenz.api.common.v1.market.Power quantity = 7;
// ...
// Optional; Applicable for ICEBERG orders. This is the quantity
// of the order to be displayed in the order book.
- frequenz.api.common.v1.market.Energy display_quantity = 10;
+ frequenz.api.common.v1.market.Power display_quantity = 10;
// ...
// Optional user-defined payload individual to a specific order. This can be
// any data that needs to be associated with the order.
//
// The field can store e.g. JSON objects containing details involved in the
// order. This feature can simplify application development by eliminating the
// need for complicated state management to remember the specifics of each
// order.
//
// By embedding this "state" within the order itself, you can include
// specifics like which microgrids consume or provide how much power. This
// makes it easier to manage complex orders and can simplify the logic
// required in applications.
//
// Example JSON payload:
// {
// "microgrids": [
// {
// "microgrid_id": "1",
- // "mwh": 1.0
+ // "mw": 1.0
// },
// {
// "microgrid_id": "2",
- // "mwh": 0.5
+ // "mw": 0.5
// }
// ]
// }
//
// In this example, if the order is exectuted, these microgrids might consume
// the electricity mentioned in the example JSON payload.
google.protobuf.Struct payload = 13;
}
// Represents an order with full details, including its ID, state and associated
// UTC timestamps.
message OrderDetail {
// Remaining open quantity for this order.
- frequenz.api.common.v1.market.Energy open_quantity = 4;
+ frequenz.api.common.v1.market.Power open_quantity = 4;
// Filled quantity for this order.
- frequenz.api.common.v1.market.Energy filled_quantity = 5;
+ frequenz.api.common.v1.market.Power filled_quantity = 5;
}
// Represents a private trade in the electricity market.
//
// !!! note
// This represents either the buy or sell side of a trade which is
// different to public trade information which always represents both
// sides of a market.
message Trade {
// The executed quantity of the trade.
- frequenz.api.common.v1.market.Energy quantity = 8;
+ frequenz.api.common.v1.market.Power quantity = 8;
}
// Represents a public trade in the market.
//
// ...
message PublicTrade {
// The executed quantity of the contract traded.
- frequenz.api.common.v1.market.Energy quantity = 7;
+ frequenz.api.common.v1.market.Power quantity = 7;
}
// Request to update an existing order for a given Gridpool.
message UpdateGridpoolOrderRequest {
// Optional; The updated quantity of the contract being traded,
- // specified in MWh.
+ // specified in MW.
- frequenz.api.common.v1.market.Energy quantity = 3;
+ frequenz.api.common.v1.market.Power quantity = 3;
// ...
// Optional; Applicable for ICEBERG orders. This is the updated quantity
// of the order to be displayed in the order book.
- frequenz.api.common.v1.market.Energy display_quantity = 6;
+ frequenz.api.common.v1.market.Power display_quantity = 6;
}Use cases
The update to electricity_trading.proto ensures the correct use of MW for power quantities in spot market trading, as opposed to MWh, which is used for energy. Currently, the electricity_trading.proto uses MWh to represent the quantity of power traded in spot markets, which is incorrect. In spot markets, power is traded in MW while the prices are set in EUR/MWh. These changes will align the protocol with standard market practices and avoid any misinterpretation of the data.
Alternatives and workarounds
No response
Additional context
No response
What's needed?
We need to make the following updates to the Frequenz open-source repository to correctly represent power quantities in MW for electricity trading in spot markets:
Proposed solution
The new Power.proto file should be created in the common/v1/market/ package. This will represent power in MW. Below is the proposed file structure:
Powerfor Quantity RepresentationWe also need to modify the electricity_trading.proto to reflect that spot market trades deal in MW for the quantity, while prices remain in EUR/MWh. The existing Energy field in the Order message should be replaced by Power.
Here is the proposed diff for this update:
// Represents an order in the electricity market. message Order { // The quantity of power being traded, specified in MW (Megawatts) + // + // !!! note + // Spot market trades specify power in MW, while prices are quoted in [Currency]/MWh. + // + // !!! example + // For a 15-minute contract: + // - If you trade 10 MW of power at a price of 50 [Currency]/MWh, the total power traded is 10 MW. + // - The total energy delivered over 15 minutes is: + // Energy (MWh) = Power (MW) * Time (hours) = 10 MW * 0.25 hours = 2.5 MWh. + // - The total cost for this 15-minute trade is: + // Total Cost = Energy (MWh) * Price ([Currency]/MWh) = 2.5 MWh * 50 [Currency]/MWh = 125 [Currency]. - frequenz.api.common.v1.market.Energy quantity = 7; + frequenz.api.common.v1.market.Power quantity = 7; // ... // Optional; Applicable for ICEBERG orders. This is the quantity // of the order to be displayed in the order book. - frequenz.api.common.v1.market.Energy display_quantity = 10; + frequenz.api.common.v1.market.Power display_quantity = 10; // ... // Optional user-defined payload individual to a specific order. This can be // any data that needs to be associated with the order. // // The field can store e.g. JSON objects containing details involved in the // order. This feature can simplify application development by eliminating the // need for complicated state management to remember the specifics of each // order. // // By embedding this "state" within the order itself, you can include // specifics like which microgrids consume or provide how much power. This // makes it easier to manage complex orders and can simplify the logic // required in applications. // // Example JSON payload: // { // "microgrids": [ // { // "microgrid_id": "1", - // "mwh": 1.0 + // "mw": 1.0 // }, // { // "microgrid_id": "2", - // "mwh": 0.5 + // "mw": 0.5 // } // ] // } // // In this example, if the order is exectuted, these microgrids might consume // the electricity mentioned in the example JSON payload. google.protobuf.Struct payload = 13; } // Represents an order with full details, including its ID, state and associated // UTC timestamps. message OrderDetail { // Remaining open quantity for this order. - frequenz.api.common.v1.market.Energy open_quantity = 4; + frequenz.api.common.v1.market.Power open_quantity = 4; // Filled quantity for this order. - frequenz.api.common.v1.market.Energy filled_quantity = 5; + frequenz.api.common.v1.market.Power filled_quantity = 5; } // Represents a private trade in the electricity market. // // !!! note // This represents either the buy or sell side of a trade which is // different to public trade information which always represents both // sides of a market. message Trade { // The executed quantity of the trade. - frequenz.api.common.v1.market.Energy quantity = 8; + frequenz.api.common.v1.market.Power quantity = 8; } // Represents a public trade in the market. // // ... message PublicTrade { // The executed quantity of the contract traded. - frequenz.api.common.v1.market.Energy quantity = 7; + frequenz.api.common.v1.market.Power quantity = 7; } // Request to update an existing order for a given Gridpool. message UpdateGridpoolOrderRequest { // Optional; The updated quantity of the contract being traded, - // specified in MWh. + // specified in MW. - frequenz.api.common.v1.market.Energy quantity = 3; + frequenz.api.common.v1.market.Power quantity = 3; // ... // Optional; Applicable for ICEBERG orders. This is the updated quantity // of the order to be displayed in the order book. - frequenz.api.common.v1.market.Energy display_quantity = 6; + frequenz.api.common.v1.market.Power display_quantity = 6; }Use cases
The update to electricity_trading.proto ensures the correct use of MW for power quantities in spot market trading, as opposed to MWh, which is used for energy. Currently, the electricity_trading.proto uses MWh to represent the quantity of power traded in spot markets, which is incorrect. In spot markets, power is traded in MW while the prices are set in EUR/MWh. These changes will align the protocol with standard market practices and avoid any misinterpretation of the data.
Alternatives and workarounds
No response
Additional context
No response