Commitments

Overview

A Commitment is the economic abstraction FlexMeasures uses to express market positions and soft constraints (preferences) inside the scheduler. Commitments are converted to linear objective terms; all non-negotiable operational limits are modelled separately as Pyomo constraints.

A commitment describes:

a baseline quantity over time (the contracted or preferred position), and
marginal prices for upwards and downwards deviations from that baseline.

The scheduler converts all provided commitments into terms in the optimization objective function so that the solver minimizes the total deviation cost across the schedule horizon. Absolute physical limitations (for example generator or line capacities) are not modelled as commitments — those are enforced as Pyomo constraints.

Key properties

Each Commitment has the following important attributes (high level):

name — a logical string identifier (e.g. "energy", "production peak").
device — optional: restricts the commitment to a single device; otherwise it is an EMS/site-level commitment.
index — the DatetimeIndex (time grid) on which the series are defined.
quantity — the baseline Series (per slot or per group).
upwards_deviation_price — Series defining marginal cost/reward for upward deviations.
downwards_deviation_price — Series defining marginal cost/reward for downward deviations.
_type — grouping indicator: 'each' or 'any' (see Grouping below).

Sign convention (flows vs stocks)

Flow commitments (e.g. power/energy flows):
- A positive baseline quantity denotes consumption.
  - Actual > baseline → upwards deviation (more consumption).
  - Actual < baseline → downwards deviation (less consumption).
- A negative baseline quantity denotes production (feed-in).
  - Actual less negative (i.e. closer to zero) → upwards deviation (less production).
  - Actual more negative → downwards deviation (more production).
Stock commitments (e.g. state of charge for storage):
- quantity is the target stock level; deviations above/below that target are priced via the upwards/downwards price series.

Soft vs hard semantics

Commitments in FlexMeasures are soft by design: they represent economic penalties or rewards that the optimizer considers when building schedules. Hard operational constraints (such as physical power limits or strict device interlocks) are expressed separately as Pyomo constraints in the scheduling model. If a “hard” behaviour is required from a commitment, assign very large penalty prices, but prefer modelling non-negotiable limits as Pyomo constraints.

Converting flex-context fields into commitments

Users may supply preferences and price fields in the flex-context. The scheduler translates the relevant fields into one or more Commitment objects before calling the optimizer.

Typical translations include:

tariffs (consumption-price, production-price) → an "energy" FlowCommitment with zero baseline so net consumption/production is priced;
peak/excess limits (site-peak-production, site-peak-production-price, etc.) → dedicated peak FlowCommitment(s);
storage-related fields (soc-minima, soc-minima-breach-price, etc.) → StockCommitment(s).

A short example

Below is a compact example showing how the scheduler conceptually creates an "energy" flow commitment from a (per-slot) tariff:

from pandas import Series, date_range
from flexmeasures.data.models.planning import FlowCommitment

index = date_range(start="2025-01-01 00:00", periods=24, freq="H")
# zero baseline → the asset may consume or produce; deviations are priced.
baseline = Series(0.0, index=index)

# consumption and production tariffs (per kWh)
consumption_price = Series(0.20, index=index)  # 0.20 EUR/kWh for consumption
production_price = Series(-0.05, index=index)  # -0.05 EUR/kWh reward for production

energy_commitment = FlowCommitment(
    name="energy",
    index=index,
    quantity=baseline,
    upwards_deviation_price=consumption_price,
    downwards_deviation_price=production_price,
    _type="each"
)

The scheduler sets up such commitments (site-level and device-level) and, together with any prior commitments, hands them to the linear optimizer.

Examples (commitments commonly derived from flex-context)

The examples below map the most common flex-context semantics to the commitments the scheduler constructs.

Energy (tariff)
- Fields used: consumption-price, production-price.
- Commitment: Flow commitment named "energy" with zero baseline and the two price series as upwards/downwards deviation prices.
Peak consumption
- Fields used: site-peak-consumption (baseline) and site-peak-consumption-price (upwards-deviation price); the downwards price is set to 0.
- Commitment: Flow commitment named "consumption peak"; positive baseline values denote the prior consumption peak associated with sunk costs, and the upwards price penalises going beyond that baseline.
Peak production / peak feed-in
- Fields used: site-peak-production (baseline) and site-peak-production-price (downwards-deviation price); the upwards price is set to 0.
- Commitment: Flow commitment named "production peak"; negative baseline values denote the prior production peak associated with sunk costs, and the downwards price penalises going beyond that baseline.
Consumption capacity
- Fields used: site-consumption-capacity (baseline), and site-consumption-breach-price (upwards-deviation price); the downwards price is set to 0.
- Commitment: Flow commitment named "consumption breach"; positive baseline values denote the allowed consumption limit and the upwards price penalises going beyond that limit.
Production capacity
- Fields used: site-production-capacity (baseline) and site-production-breach-price (downwards-deviation price); the upwards price is set to 0.
- Commitment: Flow commitment named "production breach"; negative baseline values denote the allowed production limit and the downwards price penalises going beyond that limit.
SOC minima / maxima (storage preferences)
- Fields used: soc-minima, soc-minima-breach-price, soc-maxima and soc-maxima-breach-price.
- Commitment: StockCommitment(s) that price deviations below minima or above maxima. Hard storage capacities are set through soc-min and soc-max instead and are modelled as Pyomo constraints.
Power bands per device
- Fields used: consumption-capacity and production-capacity (baselines), consumption-breach-price (upwards-deviation price, with 0 downwards) and production-breach-price (downwards-deviation price, with 0 upwards).
- Commitment: FlowCommitment with either baseline and corresponding prices.

Grouping across time and devices

_type == 'each': penalise deviations per time slot (default for time series).
_type == 'any': treat the whole commitment horizon as one group (useful for peak-style penalties where only the maximum over the window should be counted).

Note

Near-term feature: support for grouping over devices is planned and documented here. When enabled, grouping over devices lets you express soft constraints that aggregate deviations across a set of devices, for example, an intermediate capacity constraint from a feeder shared by a group of devices (via flow commitments), or multiple power-to-heat devices that feed a shared thermal buffer (via stock commitments).

Advanced: mathematical formulation

For a compact formulation of how commitments enter the optimization problem, see Storage device scheduler: Linear model.