Replace nb-scenarios with scenario playlist in scenario-scope (#206)

* Replace nb-scenarios with scenario playlist in scenario-scope

The scenario-scope config now accepts either an inline include/exclude
declaration (with support for 1-based integer indices and 'a-b' range
strings) or a playlist-file reference pointing to a flat JSON array of
1-based integers. Both forms resolve to a sorted, deduplicated list of
0-based MC scenario indices consumed by the solver.

nb-scenarios is removed: the pydantic extra="forbid" policy makes any
YAML that still uses it a hard validation error. All test fixtures and
inline config strings have been migrated to the new include form.
validate_optim_config gains an optional scenario_builder parameter to
cross-check playlist indices against every defined scenario group.

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Update uv.lock after dependency resolution

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Fix black and isort formatting

Two lines wrapped to 88 chars in parsing.py; one extra blank line
removed after import in the test file.

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Improve scenario-scope: string ints, eager cache, missing tests

- _expand_entries now accepts string integers like "5" in addition to
  int 5 and range "1-10", treating them identically after stripping
- ScenarioScopeConfig stores scenario_ids in a PrivateAttr cache so
  resolution happens at most once per instance
- load_optim_config triggers eager resolution after path resolution,
  so the playlist file is read exactly once at load time and I/O
  errors surface immediately
- New tests: string-integer entries, cache identity (file deleted after
  load), and validate_optim_config ScenarioBuilder cross-check

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Fix playlist loading: wrap I/O errors as ValueError, reject JSON booleans

FileNotFoundError and json.JSONDecodeError from _load_playlist now surface
as ValueError so callers always receive a consistent exception type.
JSON boolean values (true/false) are now explicitly rejected — bool is a
subclass of int in Python so they previously slipped through the isinstance
check silently.  Three new tests cover each case.

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Update documentation for scenario-scope playlist feature

- optim-config.md: replace nb-scenarios section with full description of
  the inline (include/exclude) and playlist-file forms, with examples,
  validation rules, and updated Python API snippets
- scenario-builder.md: remove stale nb-scenarios reference; link to
  validate_optim_config cross-check
- CHANGELOG.md: add [Unreleased] entry summarising the playlist changes;
  fix the 0.1.0 entry that still mentioned nb_scenarios

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Reject boolean values in inline include/exclude lists

Pydantic coerces True/False to 1/0 before _expand_entries sees them, so
the check must happen at the field_validator(mode="before") layer. A
field_validator on include and exclude now raises ValueError for any bool
item, making the behaviour consistent with playlist-file which already
rejects JSON booleans. Two new tests cover include=[True] and
exclude=[False].

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Switch scenario-scope to 0-based indexing throughout

All user-facing scenario index surfaces (optim-config.yml include/exclude
and JSON playlist files) now use 0-based indices, consistent with the
modeler-scenariobuilder.dat convention. The internal representation is
unchanged (already 0-based), so only the boundary conversion code is
affected:

- _expand_entries: removed the '- 1' offset; lower bound is now >= 0
- _load_playlist: removed the '- 1' offset; lower bound is now >= 0
- _resolve_inline warning: no longer adds 1 back when reporting orphans
- Range 'a-b' now means [a, b] inclusive (both 0-based)

All test fixtures, inline config strings, unit tests and documentation
updated accordingly. 'include: [0]' now means the first scenario (was 1).

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Fix CHANGELOG: restore accurate 0.1.0 entry, add inline boolean note

- 0.1.0 entry: restore nb_scenarios description (that is what was shipped
  in 0.1.0; the playlist feature is in [Unreleased])
- [Unreleased] other-changes bullet: broaden boolean rejection note to
  cover both inline include/exclude lists and JSON playlist files

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Allow exclude with playlist-file; update docstrings throughout

exclude is no longer restricted to the inline include form — it now applies
to both base-set forms (include and playlist-file). The exclude logic was
lifted out of _resolve_inline (now removed) into _compute_scenario_ids so
it runs uniformly after the base set is built.

- _check_constraints: 'exclude' now requires include OR playlist-file
- _load_playlist: returns Set[int] instead of List[int]; sorting deferred
  to _compute_scenario_ids after exclude is applied
- _compute_scenario_ids: single unified method handles both forms + exclude
- Warning message updated: 'include set' → 'base set'

Docstrings updated:
- ScenarioScopeConfig: full class docstring documenting both forms,
  exclude compatibility, caching behaviour, and index convention
- _expand_entries: clarified entry formats and boolean handling note
- validate_optim_config: enumerated bullet-point list of all checks
- ScenarioBuilder.validate_mc_scenarios: documents return contract

Four new tests cover playlist-file + exclude (basic, range, all-excluded,
orphan warning). Updated test for the relaxed exclude-without-base error.

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

* Fix validate_mc_scenarios error message; update load_optim_config docstring

validate_mc_scenarios was still converting indices to 1-based in its error
message after the 0-based switch. Error now reports the raw 0-based indices
and the correct range (0–N-1).

load_optim_config docstring replaced: removes the stale 'components_path'
reference and documents the two extra steps the function performs beyond
plain YAML parsing (relative path resolution and eager scenario_ids
population).

https://claude.ai/code/session_01EfjU9tBfdyZ9nZmQFCe5uU

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: aoustry

docs/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to GemsPy are documented here.
 
+## [Unreleased]
+
+### Scenario-scope playlist (replaces `nb-scenarios`)
+
+The `scenario-scope` section of `optim-config.yml` now supports a full
+playlist mechanism.  The old `nb-scenarios` integer key is removed and raises
+a validation error if still present.
+
+Scenario indices are **0-based** throughout, consistent with the
+`modeler-scenariobuilder.dat` convention.
+
+**Inline form** — specify scenarios with integers, string-integers, and
+inclusive `"a-b"` range strings:
+
+~~~ yaml
+scenario-scope:
+  include:
+    - "0-49"
+    - 74
+    - "89-99"
+  exclude:
+    - 9
+    - 14
+~~~
+
+**Playlist-file form** — point to a flat JSON array of 0-based integers,
+useful for machine-generated playlists:
+
+~~~ yaml
+scenario-scope:
+  playlist-file: mc_playlist.json
+~~~
+
+Other changes:
+
+- `exclude` is now compatible with both `include` and `playlist-file`.
+  Use it to subtract a few scenarios at run time without modifying the
+  playlist file.
+- `validate_optim_config()` now accepts an optional `scenario_builder`
+  argument and cross-checks all playlist indices against every scenario group,
+  raising a `ValueError` for out-of-bounds indices.
+- The playlist is resolved and cached exactly once at `load_optim_config()`
+  time; I/O and format errors surface immediately as `ValueError`.
+- Boolean values (`true`/`false`) are explicitly rejected in both inline
+  lists and JSON playlist files.
+
+---
+
 ## [0.1.0] - 2026-04-30
 
 ### Study folder structure
@@ -26,7 +74,7 @@ A new `optim-config.yml` file controls all aspects of a simulation run:
 - **`resolution.mode`** — four strategies: `frontal`, `sequential-subproblems`, `parallel-subproblems`, `benders-decomposition`
 - **`resolution.block_length` / `block_overlap`** — time-window size and overlap for sequential/parallel modes
 - **`time_scope`** — `first_time_step` / `last_time_step`
-- **`scenario_scope.nb_scenarios`** — number of Monte-Carlo scenarios to run
+- **`scenario_scope.nb_scenarios`** — number of Monte-Carlo scenarios to run (replaced by the playlist mechanism in a later release)
 - **`solver_options`** — solver name (default: HiGHS), log verbosity, and free-form solver parameters
 - **`models[].model_decomposition`** — per-model assignment of variables, constraints, and objective contributions to `master`, `subproblems`, or `master-and-subproblems` (used for Benders decomposition)
 - **`models[].out_of_bounds_processing`** — per-constraint handling of time indices that fall outside the horizon (`cyclic` or `drop`)

docs/user-guide/optim-config.md

@@ -26,9 +26,10 @@ time-scope:
   first-time-step: 0
   last-time-step: 8759   # 8760 hourly timesteps → one year
 
-# Number of Monte-Carlo scenarios to run
+# Monte-Carlo scenarios to simulate (0-based, inline form)
 scenario-scope:
-  nb-scenarios: 10
+  include:
+    - "0-9"   # scenarios 0 through 9 (10 scenarios)
 
 # Solver settings
 solver-options:
@@ -66,13 +67,115 @@ The total number of timesteps solved is `last-time-step − first-time-step + 1`
 
 ## `scenario-scope`
 
+Selects which Monte-Carlo scenarios to simulate.  Indices are **0-based**,
+consistent with the `modeler-scenariobuilder.dat` file convention.
+
+The base scenario set is defined by exactly one of two mutually exclusive
+keys: `include` (inline) or `playlist-file` (from a JSON file).  `exclude`
+is optional and applies to **either** form.
+
+### Inline form (`include` / `exclude`)
+
+Specify scenarios directly in the YAML using individual integers, string
+integers, and inclusive `"a-b"` range strings.
+
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `nb-scenarios` | int | `1` | Number of Monte-Carlo scenarios |
+| `include` | list | — | Scenarios to run (required in inline form) |
+| `exclude` | list | — | Scenarios to remove from the base set (optional) |
+
+Each entry in `include` or `exclude` may be:
+
+- An integer: `5` → scenario 5
+- A string integer: `"5"` → scenario 5 (identical to `5`)
+- A range: `"0-9"` → scenarios 0 through 9 inclusive (10 scenarios)
 
-Scenario indices run from `0` to `nb-scenarios − 1`.  If a
-[scenario builder](scenario-builder.md) file is present, these indices are
-mapped to data-series columns by that file.
+**Examples:**
+
+~~~ yaml
+# Run a single scenario
+scenario-scope:
+  include:
+    - 0
+
+# Run scenarios 0 to 99
+scenario-scope:
+  include:
+    - "0-99"
+
+# Run scenarios 0–19 and 49–59, but skip 9 and 14
+scenario-scope:
+  include:
+    - "0-19"
+    - "49-59"
+  exclude:
+    - 9
+    - 14
+~~~
+
+**Rules:**
+
+- All indices must be ≥ 0.
+- Overlapping entries in `include` are deduplicated automatically.
+- Excludes that do not appear in the base set produce a warning and have no effect.
+- Output is always sorted in ascending order.
+- `exclude` cannot be used without `include` or `playlist-file`.
+
+**Default behaviour** (no `scenario-scope` key at all, or an empty block):
+runs scenario 0 only.
+
+---
+
+### Playlist-file form (`playlist-file`)
+
+Point to a JSON file containing a flat array of 0-based integer scenario
+indices.  Useful when the list of scenarios is generated programmatically or
+is too large to embed in YAML.
+
+| Key | Type | Description |
+|---|---|---|
+| `playlist-file` | path | Path to a JSON playlist (relative to `optim-config.yml`) |
+
+~~~ yaml
+scenario-scope:
+  playlist-file: mc_playlist.json   # resolved relative to optim-config.yml
+~~~
+
+The referenced file must contain a flat JSON array of non-negative integers:
+
+~~~ json
+[0, 2, 4, 6, 8, 10, 12]
+~~~
+
+`exclude` can be combined with `playlist-file` to subtract specific scenarios
+at run time without modifying the file:
+
+~~~ yaml
+scenario-scope:
+  playlist-file: mc_playlist.json
+  exclude:
+    - 4
+    - "8-10"
+~~~
+
+GemsPy reads and validates the playlist eagerly when `load_optim_config()` is
+called, so any I/O or format errors surface immediately at load time.
+
+**Rules:**
+
+- The file must be a flat JSON array of integers (no booleans, strings, or objects).
+- All indices must be ≥ 0.
+- Duplicates are silently removed; the result is sorted ascending.
+- `include` and `playlist-file` are mutually exclusive.
+
+---
+
+### ScenarioBuilder cross-validation
+
+If a [scenario builder](scenario-builder.md) file is present,
+`validate_optim_config()` checks that every scenario index in the playlist is
+defined for every scenario group.  Out-of-bounds indices raise a `ValueError`
+listing the affected groups.
 
 ---
 
@@ -238,17 +341,24 @@ from gems.optim_config import (
 # Load from file (returns None if the file does not exist)
 config = load_optim_config(Path("my_study/input/optim-config.yml"))
 
-# Build programmatically
+# Build programmatically — inline form (scenarios 0–9)
 config = OptimConfig(
     time_scope=TimeScopeConfig(first_time_step=0, last_time_step=8759),
-    scenario_scope=ScenarioScopeConfig(nb_scenarios=10),
+    scenario_scope=ScenarioScopeConfig(include=["0-9"]),
     solver_options=SolverOptionsConfig(name="highs", logs=False),
     resolution=ResolutionConfig(
         mode=ResolutionMode.SEQUENTIAL_SUBPROBLEMS,
         block_length=168,
     ),
 )
 
+# Build programmatically — playlist-file form
+from pathlib import Path
+config_pf = OptimConfig(
+    time_scope=TimeScopeConfig(first_time_step=0, last_time_step=8759),
+    scenario_scope=ScenarioScopeConfig(playlist_file=Path("mc_playlist.json")),
+)
+
 # Pass to SimulationSession
 from gems.session import SimulationSession
 from gems.study import load_study

docs/user-guide/scenario-builder.md

@@ -8,10 +8,10 @@ scenario index `i` always maps to column `i` of every timeseries file.
 
 ## Motivation
 
-A study with `nb-scenarios = 100` may have some components (e.g. wind farms)
-whose data only has 10 distinct columns, while others (e.g. demand) have 100.
-The scenario builder lets you express this mapping explicitly, so GemsPy reads
-the right column for each component and scenario.
+A study that simulates 100 MC scenarios may have some components (e.g. wind
+farms) whose data only has 10 distinct columns, while others (e.g. demand)
+have 100.  The scenario builder lets you express this mapping explicitly, so
+GemsPy reads the right column for each component and scenario.
 
 ---
 
@@ -55,9 +55,11 @@ demand, 3 = 4
 ```
 
 !!! note
-    All MC scenario indices (`0` to `nb-scenarios - 1`) must be listed for every
-    group that appears in the file.  Missing entries raise a `ValueError` at
-    load time.
+    Every MC scenario index that appears in the simulation playlist must be
+    listed for every group in the file.  Missing entries raise a `ValueError`
+    at load time.  `validate_optim_config()` cross-checks the
+    [scenario-scope playlist](optim-config.md#scenario-scope) against the
+    scenario builder and reports any out-of-bounds indices.
 
 ---