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

Author: claude

docs/CHANGELOG.md

@@ -10,21 +10,24 @@ 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:
-    - "1-50"
-    - 75
-    - "90-100"
+    - "0-49"
+    - 74
+    - "89-99"
   exclude:
-    - 10
-    - 15
+    - 9
+    - 14
 ~~~
 
-**Playlist-file form** — point to a flat JSON array of 1-based integers,
+**Playlist-file form** — point to a flat JSON array of 0-based integers,
 useful for machine-generated playlists:
 
 ~~~ yaml

docs/user-guide/optim-config.md

@@ -26,10 +26,10 @@ time-scope:
   first-time-step: 0
   last-time-step: 8759   # 8760 hourly timesteps → one year
 
-# Monte-Carlo scenarios to simulate (1-based, inline form)
+# Monte-Carlo scenarios to simulate (0-based, inline form)
 scenario-scope:
   include:
-    - "1-10"   # scenarios 1 through 10
+    - "0-9"   # scenarios 0 through 9 (10 scenarios)
 
 # Solver settings
 solver-options:
@@ -67,9 +67,8 @@ The total number of timesteps solved is `last-time-step − first-time-step + 1`
 
 ## `scenario-scope`
 
-Selects which Monte-Carlo scenarios to simulate.  Indices in the YAML are
-**1-based** (matching the scenario-builder convention); GemsPy converts them
-to 0-based indices internally.
+Selects which Monte-Carlo scenarios to simulate.  Indices are **0-based**,
+consistent with the `modeler-scenariobuilder.dat` file convention.
 
 Two mutually exclusive forms are supported:
 
@@ -87,41 +86,41 @@ Each entry in `include` or `exclude` may be:
 
 - An integer: `5` → scenario 5
 - A string integer: `"5"` → scenario 5 (identical to `5`)
-- A range: `"1-10"` → scenarios 1 through 10 (inclusive)
+- A range: `"0-9"` → scenarios 0 through 9 inclusive (10 scenarios)
 
 **Examples:**
 
 ~~~ yaml
 # Run a single scenario
 scenario-scope:
   include:
-    - 1
+    - 0
 
-# Run scenarios 1 to 100
+# Run scenarios 0 to 99
 scenario-scope:
   include:
-    - "1-100"
+    - "0-99"
 
-# Run scenarios 1–20 and 50–60, but skip 10 and 15
+# Run scenarios 0–19 and 49–59, but skip 9 and 14
 scenario-scope:
   include:
-    - "1-20"
-    - "50-60"
+    - "0-19"
+    - "49-59"
   exclude:
-    - 10
-    - 15
+    - 9
+    - 14
 ~~~
 
 **Rules:**
 
-- All indices must be ≥ 1.
+- All indices must be ≥ 0.
 - Overlapping entries in `include` are deduplicated automatically.
 - Excludes that do not appear in `include` produce a warning and have no effect.
 - Output is always sorted in ascending order.
 - `exclude` cannot be used without `include`.
 
 **Default behaviour** (no `scenario-scope` key at all, or an empty block):
-runs scenario 1 only.
+runs scenario 0 only.
 
 ---
 
@@ -153,7 +152,7 @@ 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 ≥ 1.
+- All indices must be ≥ 0.
 - Duplicates are silently removed; the result is sorted ascending.
 - `include` / `exclude` and `playlist-file` are mutually exclusive.
 
@@ -330,10 +329,10 @@ 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 — inline form (scenarios 1–10)
+# Build programmatically — inline form (scenarios 0–9)
 config = OptimConfig(
     time_scope=TimeScopeConfig(first_time_step=0, last_time_step=8759),
-    scenario_scope=ScenarioScopeConfig(include=["1-10"]),
+    scenario_scope=ScenarioScopeConfig(include=["0-9"]),
     solver_options=SolverOptionsConfig(name="highs", logs=False),
     resolution=ResolutionConfig(
         mode=ResolutionMode.SEQUENTIAL_SUBPROBLEMS,

src/gems/optim_config/parsing.py

@@ -136,37 +136,29 @@ def parsed_parameters(self) -> Dict[str, Any]:
 
 
 def _expand_entries(entries: List[Union[int, str]]) -> Set[int]:
-    """Expand 1-based ints and inclusive 'a-b' range strings into a set of 0-based indices."""
+    """Expand 0-based ints and inclusive 'a-b' range strings into a set of 0-based indices."""
     result: Set[int] = set()
     for entry in entries:
         if isinstance(entry, int):
-            if entry < 1:
-                raise ValueError(f"Scenario index must be >= 1 (1-based), got {entry}")
-            result.add(entry - 1)
+            if entry < 0:
+                raise ValueError(f"Scenario index must be >= 0, got {entry}")
+            result.add(entry)
         else:
             s = str(entry).strip()
             if re.fullmatch(r"\d+", s):
                 val = int(s)
-                if val < 1:
-                    raise ValueError(
-                        f"Scenario index must be >= 1 (1-based), got {val}"
-                    )
-                result.add(val - 1)
+                result.add(val)
             else:
                 match = re.fullmatch(r"(\d+)-(\d+)", s)
                 if not match:
                     raise ValueError(
                         f"Invalid entry {entry!r}: expected an integer or a range 'a-b'"
-                        " (e.g. '5' or '1-10')"
+                        " (e.g. '5' or '0-9')"
                     )
                 a, b = int(match.group(1)), int(match.group(2))
-                if a < 1:
-                    raise ValueError(
-                        f"Range start must be >= 1 (1-based), got {a} in {entry!r}"
-                    )
                 if a > b:
                     raise ValueError(f"Range start must be <= end, got {entry!r}")
-                result.update(range(a - 1, b))
+                result.update(range(a, b + 1))
     return result
 
 
@@ -227,19 +219,19 @@ def _load_playlist(self) -> List[int]:
             raise ValueError(
                 f"'{self.playlist_file}' must contain a flat JSON array of integers"
             )
-        if any(x < 1 for x in data):
+        if any(x < 0 for x in data):
             raise ValueError(
-                f"'{self.playlist_file}': all scenario indices must be >= 1 (1-based)"
+                f"'{self.playlist_file}': all scenario indices must be >= 0"
             )
-        return sorted({x - 1 for x in data})
+        return sorted(set(data))
 
     def _resolve_inline(self) -> List[int]:
         included = _expand_entries(self.include or [])
         excluded = _expand_entries(self.exclude or [])
         orphans = excluded - included
         if orphans:
             warnings.warn(
-                f"Excluded scenario indices {sorted(o + 1 for o in orphans)} "
+                f"Excluded scenario indices {sorted(orphans)} "
                 "are not in the include set and have no effect",
                 UserWarning,
                 stacklevel=2,

tests/e2e/functional/studies/13_1/input/optim-config.yml

@@ -20,7 +20,7 @@ solver-options:
 
 scenario-scope:
   include:
-    - 1
+    - 0
 
 models:
   - id: lib_example_13_1.generator_with_continuous_invest

tests/e2e/functional/studies/13_2/input/optim-config.yml

@@ -20,7 +20,7 @@ solver-options:
 
 scenario-scope:
   include:
-    - 1
+    - 0
 
 models:
   - id: lib_example_13_2.generator_with_discrete_invest

tests/e2e/functional/studies/7_4/input/optim-config.yml

@@ -9,4 +9,4 @@ solver-options:
 
 scenario-scope:
   include:
-    - 1
+    - 0

tests/e2e/functional/test_optim_modes.py

@@ -42,7 +42,7 @@
       parameters: ""
     scenario-scope:
       include:
-        - 1
+        - 0
     resolution:
       mode: frontal
 """)
@@ -57,7 +57,7 @@
       parameters: ""
     scenario-scope:
       include:
-        - 1
+        - 0
     resolution:
       mode: parallel-subproblems
       block-length: 168
@@ -73,7 +73,7 @@
       parameters: ""
     scenario-scope:
       include:
-        - 1
+        - 0
     resolution:
       mode: sequential-subproblems
       block-length: 168

tests/e2e/functional/test_rolling_horizon_suboptimality.py

@@ -78,7 +78,7 @@
       parameters: ""
     scenario-scope:
       include:
-        - 1
+        - 0
     models:
       - id: rolling-horizon-lib.storage
         out-of-bounds-processing: