euroflex_bess_lab

euroflex_bess_lab is a commercial-grade benchmarking, scheduling, revision, and audit framework for European BESS workflows.

The release shape is intentionally two-layered:

• the narrow GA promise remains the Belgium portfolio + shared-POI schedule_revision path with da_plus_afrr
• the new live-supported Dutch secondary surface brings TenneT-backed Netherlands market data into the same normalization, validation, revision, reconciliation, and operator-handoff workflow

From TenneT live data to operator handoff: live Dutch inputs, provenance-aware normalization, revision-aware scheduling, and operator-facing exports on a stable secondary Netherlands surface.

The Belgium canonical path remains the narrow GA promise: forecast inputs turn into checkpoint revisions, asset SoC movement, expected-versus-realized value bridges, and the final operator plus bid-planning handoff artifacts.

This public release is the open-core base for operator-facing benchmarking, scheduling support, revision, audit, and downstream handoff in European BESS workflows. Commercial integration, managed deployment, and market-specific adapters are available separately from the public core.

Release Shape

• Narrow GA: Belgium, portfolio / shared POI, schedule_revision, base_workflow: da_plus_afrr, forecast paths persistence and csv
• Stable secondary surface: Belgium and Netherlands da_only, da_plus_fcr, da_plus_afrr, and schedule_revision where the adapter support is explicit
• Live Dutch connector surface: TenneT-backed settlement prices, merit-order data, FRR activations, and derived Dutch aFRR activation price / ratio series
• Integration point: custom_python for trusted local forecast logic
• Oracle only: perfect_foresight
• Out of scope: live submission, EMS / SCADA control, autonomous trading

Install

python -m pip install euroflex-bess-lab
euroflex --version

PyPI installs the CLI and library surface. The promoted configs, canonical examples, notebooks, and full implementation docs live in this repository and on the docs site.

Narrow GA Promise

The first intentionally narrow GA promise is:

• Market: Belgium
• Scope: portfolio / shared POI
• Workflow: schedule_revision
• Base workflow: da_plus_afrr
• Forecast paths: persistence, csv
• Operator path: validate-config -> validate-data -> backtest -> reconcile -> export-schedule --profile operator -> export-bids --profile bid_planning
• Canonical config: examples/configs/canonical/belgium_full_stack.yaml

Everything else is explicitly tiered:

• perfect_foresight: oracle-only benchmark surface
• custom_python: stable integration point for trusted local forecast code
• Netherlands: promoted stable full-stack surface with live-supported TenneT ingestion, but still outside the narrow Belgium GA promise
• live submission / EMS control: out of scope

flowchart LR
    A["Visible inputs at checkpoint<br/>Belgium forecasts or Dutch live TenneT inputs"] --> B["Normalize + validate<br/>timezone alignment, provenance, contract checks"]
    B --> C["Forecast + optimizer layer<br/>persistence | csv | custom_python + market-rule scheduling"]
    C --> D["Operator handoff<br/>schedule exports + bid-planning exports"]
    D --> E["Realized settlement<br/>reconcile, update SoC, attribute deltas"]
    E --> A

Loading

Who This Is For

• BESS owners, operators, and optimizers evaluating Belgium-first scheduling and revision workflows
• flexibility aggregators and VPP teams benchmarking site or portfolio value stacking behind shared constraints
• trading, scheduling, and dispatch support teams that need operator-ready exports and bid-planning handoff
• developers, diligence teams, and revenue modelers benchmarking market-entry assumptions or private forecast models
• internal teams that want a rule-aware execution layer without rebuilding market logic from scratch

Why It Matters

• turns visible public or private forecast inputs into auditable benchmark schedules
• keeps market rules, locked commitments, portfolio constraints, and export discipline explicit
• produces operator-ready schedule and bid-planning artifacts with manifest metadata and reconciliation
• reduces the time and integration cost of rebuilding market-specific BESS workflow logic
• separates forecast IP from deterministic market-execution logic so quantitative teams can focus on forecast alpha

Where It Fits

• a public-core foundation for benchmark, scheduling support, revision, reconciliation, and audit workflows
• suitable for internal evaluation, PoCs, enterprise integration, and operator-facing support tooling
• intended to sit upstream of approval workflows, execution routers, and market-specific submission adapters
• not a turnkey all-market deployment surface without company-specific process and IT integration

5-minute Canonical Run From a Repo Checkout

These flows assume you are running from a clone of this repository, because the promoted configs and notebook assets live under examples/, notebooks/, and docs/.

git clone https://github.com/bozliu/euroflex-bess-lab.git
cd euroflex-bess-lab

Local dl environment

conda env update -f environment.yml
conda activate dl
euroflex validate-config examples/configs/canonical/belgium_full_stack.yaml
euroflex validate-data examples/configs/canonical/belgium_full_stack.yaml
euroflex backtest examples/configs/canonical/belgium_full_stack.yaml --market belgium --workflow schedule_revision
euroflex reconcile artifacts/examples/<run_id> examples/configs/canonical/belgium_full_stack.yaml
euroflex export-schedule artifacts/examples/<run_id> --profile operator
euroflex export-bids artifacts/examples/<run_id> --profile bid_planning

Docker

docker build -t euroflex-bess-lab .
docker run --rm -v "$PWD/artifacts:/app/artifacts" euroflex-bess-lab \
  euroflex validate-config examples/configs/canonical/belgium_full_stack.yaml
docker run --rm -v "$PWD/artifacts:/app/artifacts" euroflex-bess-lab \
  euroflex backtest examples/configs/canonical/belgium_full_stack.yaml \
  --market belgium \
  --workflow schedule_revision

Notebook-first

docker compose up notebooks
euroflex batch examples/batches/canonical_belgium_full_stack.yaml

Data Provenance & Sample Datasets

euroflex_bess_lab expects high-fidelity 15-minute market data for credible backtests, revision checkpoints, and operator handoff artifacts.

The examples/data/ directory contains frozen, normalized sample datasets so the quickstart, docs, CI, and public benchmarks stay deterministic without requiring API keys.

• Day-ahead prices: sourced from ENTSO-E Transparency Platform workflows
• Imbalance and reserve benchmark curves: derived from public Elia (Belgium) and TenneT (Netherlands) market publications

Bundled example data is for reproducible examples, tests, docs, and benchmarks. Bundled data is not a live operational feed or settlement-grade statement. Users are responsible for validating licensing and suitability before production use.

See the full Data provenance guide for source/operator detail, raw-vs-derived status, redistribution posture, limitations, and live-data ingestion paths.

What It Is

• A market-rule encoder for Belgium-first BESS portfolio scheduling and revision
• A shared-POI optimizer for multi-battery sites
• A checkpoint-based revision and reconciliation engine
• A human-in-the-loop export layer with benchmark, operator, bid_planning, and submission_candidate profiles
• A local service wrapper and run-registry layer for human-in-the-loop operational integration
• A stable extension point for private forecast code through custom_python

What It Is Not

• A live trading engine
• A live reserve-submission stack
• An EMS / SCADA controller
• A guarantee of realized market revenue
• A plug-and-play deployment for every market, operator, or energy company workflow

Docs

Start with:

• Quickstart
• Data provenance
• Commercial positioning
• Capability matrix
• Operator runbook
• Execution handoff
• Using TenneT live inputs
• Service API
• Run registry
• Export profiles
• Known limitations
• BYO-ML forecast provider
• Compatibility and deprecation policy

Public example surface

The curated public examples are intentionally small:

• examples/configs/canonical/belgium_full_stack.yaml
• examples/configs/canonical/netherlands_full_stack.yaml
• examples/configs/reserve/belgium_da_plus_afrr_base.yaml
• examples/configs/reserve/netherlands_da_plus_afrr_base.yaml
• examples/configs/custom/belgium_full_stack_custom_python.yaml
• examples/configs/basic/netherlands_da_only_base.yaml
• examples/configs/basic/netherlands_da_only_live_inputs.yaml
• examples/batches/canonical_belgium_full_stack.yaml

Everything else needed for tests and non-promoted scenarios lives under tests/fixtures/.