Reliability/performance upgrade: EV/BESS/PV fixes, three-phase constraints, community settlement and internal refactor

.github/workflows/run_tests.yml

@@ -1,37 +1,90 @@
-name: Repository Tests
+name: CI
 
 on:
   push:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
+  lint:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install lint dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Lint (critical rules)
+        run: |
+          python -m ruff check citylearn tests scripts/manual scripts/ci --select E9,F821
+
   test:
+    needs: lint
     runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10"]
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ matrix.python-version }}
 
       - name: Cache pip dependencies
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          key: ${{ runner.os }}-py${{ matrix.python-version }}-pip-${{ hashFiles('requirements.txt', 'test_requirements.txt', 'setup.py') }}
           restore-keys: |
-            ${{ runner.os }}-pip-    
+            ${{ runner.os }}-py${{ matrix.python-version }}-pip-
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
           pip install -r test_requirements.txt
-          pip install gymnasium
           pip install -e .
 
-
       - name: Run tests
-        run: python -m pytest --ignore=tests/scripts
+        run: python -m pytest -q --ignore=scripts/manual
+
+      - name: Performance smoke check
+        if: matrix.python-version == '3.10'
+        run: |
+          mkdir -p ${{ runner.temp }}/perf
+          python scripts/ci/perf_smoke.py \
+            --episode-steps 600 \
+            --seconds 60 \
+            --none-max-ms 30 \
+            --end-max-ms 45 \
+            --ratio-max 2.0 \
+            --baseline-file scripts/ci/perf_baseline.json \
+            --baseline-regression-ratio 3.0 \
+            --baseline-slack-ms 10.0 \
+            --metrics-output ${{ runner.temp }}/perf/perf_smoke_report.json
+
+      - name: Upload performance smoke report
+        if: always() && matrix.python-version == '3.10'
+        uses: actions/upload-artifact@v4
+        with:
+          name: perf-smoke-report
+          path: ${{ runner.temp }}/perf/perf_smoke_report.json
+          if-no-files-found: ignore

.gitignore

@@ -185,3 +185,5 @@ examples/*
 render_logs/
 SimulationData/
 results/
+runtime.csv
+*-runtime.csv

MANIFEST.in

@@ -1,2 +1,3 @@
 include citylearn/assets/*
-recursive-include citylearn/misc *
+recursive-include citylearn/misc *
+include requirements.txt

README.md

@@ -15,6 +15,11 @@ Install latest release in PyPi with `pip`:
 pip install CityLearn
 ```
 
+Optional dependency for PV autosizing (`PySAM`):
+```console
+pip install "CityLearn[pysam]"
+```
+
 ## Documentation
 Refer to the [docs](https://intelligent-environments-lab.github.io/CityLearn/).
 

citylearn/__init__.py

@@ -1 +1 @@
-__version__ = '2.5.0'
+__version__ = '2.6.0b1'

citylearn/agents/base.py

@@ -148,11 +148,12 @@ def learn(self, episodes: int = None, deterministic: bool = None, deterministic_
             deterministic = deterministic or (deterministic_finish and episode >= episodes - 1)
             observations, _ = self.env.reset()
             self.episode_time_steps = self.episode_tracker.episode_time_steps
-            terminated = False
+            terminated = self.env.terminated
+            truncated = self.env.truncated
             time_step = 0
             rewards_list = []
 
-            while not terminated:
+            while not (terminated or truncated):
                 actions = self.predict(observations, deterministic=deterministic)
 
                 # apply actions to citylearn_env
@@ -176,13 +177,23 @@ def learn(self, episodes: int = None, deterministic: bool = None, deterministic_
 
                 time_step += 1
 
-            rewards = np.array(rewards_list, dtype='float')
-            rewards_summary = {
-                'min': rewards.min(axis=0),
-                'max': rewards.max(axis=0),
-                'sum': rewards.sum(axis=0),
-                'mean': rewards.mean(axis=0)
-            }
+            if len(rewards_list) > 0:
+                rewards = np.array(rewards_list, dtype='float')
+                rewards_summary = {
+                    'min': rewards.min(axis=0),
+                    'max': rewards.max(axis=0),
+                    'sum': rewards.sum(axis=0),
+                    'mean': rewards.mean(axis=0)
+                }
+            else:
+                reward_length = len(self.action_space)
+                empty = np.zeros(reward_length, dtype='float')
+                rewards_summary = {
+                    'min': empty,
+                    'max': empty,
+                    'sum': empty,
+                    'mean': empty,
+                }
             logging.info(f'Completed episode: {episode + 1}/{episodes}, Reward: {rewards_summary}')
 
     def predict(self, observations: List[List[float]], deterministic: bool = None) -> List[List[float]]:
@@ -282,4 +293,4 @@ def predict(self, observations: List[List[float]], deterministic: bool = None) -
         self.actions = actions
         self.next_time_step()
 
-        return actions
+        return actions

citylearn/base.py

@@ -102,12 +102,22 @@ def __next_episode_time_steps(self, episode_time_steps: Union[int, List[Tuple[in
 
         splits = None
 
-        if isinstance(episode_time_steps, List):
+        if isinstance(episode_time_steps, list):
             splits = episode_time_steps
 
         else:
+            if episode_time_steps <= 0:
+                raise ValueError(f'episode_time_steps must be >= 1, got {episode_time_steps}.')
+
             earliest_start_time_step = self.__simulation_start_time_step 
             latest_start_time_step = (self.__simulation_end_time_step + 1) - episode_time_steps
+
+            if latest_start_time_step < earliest_start_time_step:
+                raise ValueError(
+                    f'episode_time_steps ({episode_time_steps}) exceeds available simulation window '
+                    f'({self.simulation_time_steps}). Reduce episode_time_steps or adjust '
+                    'simulation_start_time_step/simulation_end_time_step.'
+                )
 
             if rolling_episode_split:
                 start_time_steps = range(earliest_start_time_step, latest_start_time_step + 1)
@@ -118,10 +128,13 @@ def __next_episode_time_steps(self, episode_time_steps: Union[int, List[Tuple[in
             splits = np.array([start_time_steps, end_time_steps], dtype=int).T
             splits = splits.tolist()
 
+        if len(splits) == 0:
+            raise ValueError('No valid episode splits could be created from the provided episode_time_steps.')
+
         if random_episode_split:
             seed = int(random_seed*(self.episode + 1))
             nprs = np.random.RandomState(seed)
-            ix = nprs.choice(len(splits) - 1)
+            ix = 0 if len(splits) == 1 else int(nprs.choice(len(splits)))
 
         else:
             ix = self.episode%len(splits)
@@ -269,4 +282,4 @@ def reset_time_step(self):
         Sets `time_step` to 0.
         """
 
-        self.__time_step = 0
+        self.__time_step = 0