OSTEC Promotor Module¶

Type: OSTEC_PROMOTOR Category: Optimization Maturity: DEVELOPMENT 🟡 Execution: Asynchronous (Celery worker)

Bilateral two-stage MILP that minimizes the promoter's (e.g. Renewing) energy costs while respecting individual rationality constraints for all community members. Uses the rec_operation library.

Key difference from OSTEC Simple: energy is traded pair-by-pair between meters (bilateral structure), rather than through a collective pool.

Async execution

Calculations are dispatched to a background Celery worker. The /calculate endpoint returns immediately. Poll GET /configs/{config_id} and check last_run_status.

Configuration Schema¶

Field	Type	Default	Description
`type_coef`	string	`"coef_prop"`	Coefficient allocation method: `coef_prop` · `coef_perc` · `coef_price` · `coef_best` · `coef_tree`
`type_method`	string	`"PYOMO"`	Optimization method: `PYOMO` · `KKT` · `MO` · `Heuristic_Bilevel`
`percentage`	number	`1.0`	Fraction of BTM consumption subject to optimization (0–1)
`l_lem_mnh_value`	number	`0.01`	MNH penalization price (€/kWh)
`promoter_meter_id`	UUID	(auto)	Meter that acts as promoter (`renewing=True`). Auto-detected if omitted
`strict_pos_coeffs`	boolean	`true`	Enforce strictly positive coefficients
`total_share_coeffs`	boolean	`false`	Use total share coefficients
`l_extra`	number	`10.0`	Extra penalty weight
`l_market_buy`	number	`500.0`	Market buy price cap
`l_market_sell`	number	`-500.0`	Market sell price floor
`use_simulated_prices`	boolean	`false`	Testing only — synthetic peak/off-peak prices

{
  "type_coef": "coef_prop",
  "type_method": "PYOMO",
  "percentage": 1.0,
  "l_lem_mnh_value": 0.01
}

Activation¶

curl -X POST \
  https://<host>/core/api/communities/{community_id}/energy_management/configs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "module_type": "OSTEC_PROMOTOR",
    "horizon": 24,
    "delta_t": 1.0,
    "config_data": {
      "type_coef": "coef_prop",
      "type_method": "PYOMO",
      "percentage": 1.0,
      "l_lem_mnh_value": 0.01
    }
  }'

Triggering a Calculation¶

curl -X POST \
  "https://<host>/core/api/communities/{community_id}/energy_management/configs/{config_id}/calculate?target_date=2026-04-18" \
  -H "Authorization: Bearer <token>"

Response (async):

{
  "message": "Calculation dispatched to background worker",
  "config_id": "...",
  "module_type": "OSTEC_PROMOTOR",
  "target_date": "2026-04-18",
  "async": true
}

Poll for completion:

curl https://<host>/core/api/communities/{community_id}/energy_management/configs/{config_id} \
  -H "Authorization: Bearer <token>"
# Check last_run_status: RUNNING → SUCCESS or FAILED