Energy Management System (EMS)¶

The RECreation EMS is a modular, pluggable system for optimizing community energy use. Each module has a module_type identifier and encapsulates its own logic, configuration schema, and capabilities.

Module Architecture¶

graph TD
    Config[EMS Configuration] -->|module_type| Factory[Module Factory]
    Factory --> OSTEC[OSTEC_SIMPLE Module]
    Factory --> GDBN[GDBN_BEFLEXIBLE Module]
    Factory --> Future[... future modules]
    OSTEC -->|writes| SP[Energy Setpoints]
    GDBN -->|receives| SP
    GDBN -->|stores| FO[Flexibility Offers]

Available Modules¶

Module Type	Category	Description
`OSTEC_SIMPLE`	Optimization	Local MILP optimization of storage, EV, EWH
`GDBN_BEFLEXIBLE`	Flexibility	Receives setpoints/offers from external GDBN service (DEVELOPMENT)

Configuration¶

Each community can have one or more EMS configurations. Key configuration fields:

Field	Description
`module_type`	Which module to use
`horizon`	Optimization horizon in hours (e.g. `24`, `48`)
`delta_t`	Time step in hours (`1.0` = hourly, `0.5` = 30-min)
`strict_pos_coeffs`	Enforce non-negative allocation coefficients
`total_share_coeffs`	Normalize coefficients to sum to 1
`config_data`	Module-specific JSON config (see each module's schema)
`is_active`	Whether this configuration is active during this period
`start_date`	Required. First day (inclusive, Europe/Lisbon) on which this configuration version applies
`end_date`	Last day (inclusive) on which this configuration version applies. `null` = open-ended

Configuration Validity¶

module_type is fixed when the configuration is created. All other fields are dated: PATCH /configs/{config_id} requires start_date and changes the configuration only from that day (or for [start_date, end_date]).

A calculation uses the configuration version effective on its target date. Optimization horizons cannot be split, so a calculation whose horizon crosses a day on which the configuration or the community structure changes is rejected with 409 Conflict. Run it on each side of that day instead. See Business Validity.

Capabilities¶

Each module declares what it can do:

Capability	Description
`local_optimization`	Runs MILP or similar solver locally
`setpoint_calculation`	Produces per-resource setpoints
`storage_management`	Controls battery charge/discharge
`ev_management`	Controls EV charging schedules
`external_setpoint_reception`	Accepts setpoints pushed by external services
`external_offer_reception`	Accepts flexibility offers from external services