Source code for citylearn.internal.baseline

from __future__ import annotations

import gc
from copy import deepcopy
from dataclasses import dataclass
from typing import TYPE_CHECKING, Dict, List, Optional, Tuple

import pandas as pd

if TYPE_CHECKING:
    from citylearn.citylearn import CityLearnEnv


[docs] @dataclass class BusinessAsUsualBaselineResult: """Cached result for an operational business-as-usual sidecar run.""" env: "CityLearnEnv" kpis_v2: pd.DataFrame episode: int time_step: int ev_charge_target: str = 'full'
# EV charging targets of the native BAU, kept here so the environment can # validate its setting without importing the agents. BUSINESS_AS_USUAL_EV_CHARGE_TARGETS = ('full', 'requested')
[docs] def validate_business_as_usual_ev_charge_target(value) -> str: value = str(value) if value not in BUSINESS_AS_USUAL_EV_CHARGE_TARGETS: raise ValueError( f"ev_charge_target must be one of {sorted(BUSINESS_AS_USUAL_EV_CHARGE_TARGETS)}, got {value!r}." ) return value
[docs] class CityLearnBusinessAsUsualBaselineService: """Runs and caches the native business-as-usual baseline for an env.""" def __init__(self, env: "CityLearnEnv"): self.env = env
[docs] def run(self, force: bool = False) -> BusinessAsUsualBaselineResult: from citylearn.agents.baseline import BusinessAsUsualAgent env = self.env from citylearn.internal.temporal import input_changes if input_changes(getattr(env, '_input_snapshot', {})): raise ValueError('Native BAU inputs changed since loading; restore inputs or evaluate without the native reference') target_time_step = int(getattr(env, 'time_step', 0)) episode = int(getattr(env.episode_tracker, 'episode', 0)) cache_key = (episode, target_time_step) cache: Dict[Tuple[int, int], BusinessAsUsualBaselineResult] = getattr( env, '_business_as_usual_baseline_cache', {}, ) ev_charge_target = getattr(env, 'business_as_usual_ev_charge_target', 'full') if not force and cache_key in cache and cache[cache_key].ev_charge_target == ev_charge_target: return cache[cache_key] # Keep only the latest result. Within an episode the time step only moves forward and reset # clears the cache, so an earlier entry is never read again, yet each holds a whole sidecar # env. Release it before building the next one, this frame's handle on the cache included, # so at most one sidecar is alive. An env holds reference cycles, so dropping the last # reference does not free it; collect now rather than when the collector next runs. released = bool(cache) del cache self.clear() if released: gc.collect() baseline_env = self._new_sidecar_env() baseline_env.random_seed = env.random_seed agent = BusinessAsUsualAgent(baseline_env, ev_charge_target=ev_charge_target) baseline_env.reset() # Pair the away-EV stochastic stream with the source episode, including # repeated resets; a freshly constructed sidecar has a different episode index. import numpy as np baseline_env._ev_drift_seed = env._ev_drift_seed baseline_env._ev_drift_random_state = np.random.RandomState(env._ev_drift_seed) from citylearn import __version__ from citylearn.internal.comparison import ( configuration_differences, equipment, equipment_differences, inventory, reference_configuration, ) if inventory(baseline_env) != env._comparison_initial_inventory: raise ValueError('Native BAU initial inventory differs from the evaluated episode') differences = configuration_differences(env._comparison_initial_configuration, reference_configuration(baseline_env)) if differences: shown = '; '.join(differences[:3]) + ('; ...' if len(differences) > 3 else '') raise ValueError( f'Native BAU configuration differs from the evaluated env, as captured at its last reset, in ' f'{len(differences)} setting(s) (evaluated vs reference): {shown}. The reference is rebuilt from ' 'the schema and the constructor arguments, so it cannot follow buildings, outage settings or actions ' 'changed after loading; evaluate without the native reference ' '(include_business_as_usual=False) in that case.' ) # The inventory covers batteries and EVs only; heat pumps, heaters and storage tanks are sized too. differences = equipment_differences(env._comparison_initial_equipment, equipment(baseline_env)) if differences: shown = '; '.join(differences[:3]) + ('; ...' if len(differences) > 3 else '') raise ValueError( f'Native BAU equipment differs from the evaluated env, as captured at its last reset, in ' f'{len(differences)} parameter(s) (evaluated vs reference): {shown}. The reference rebuilds devices ' 'from the schema, so it cannot follow devices changed after loading; evaluate without the native reference ' '(include_business_as_usual=False) in that case.' ) identity = agent.comparison_identity() baseline_env._native_reference_metadata = dict( implementation='citylearn.agents.baseline.BusinessAsUsualAgent', simulator_version=__version__, definition_version=agent.DEFINITION_VERSION, observation_access=identity['observation_access'], resolved_parameters=identity['parameters'], ) while int(baseline_env.time_step) < target_time_step and not (baseline_env.terminated or baseline_env.truncated): actions = agent.predict([], deterministic=True) baseline_env._runtime_service.step_without_feedback(actions) kpis_v2 = baseline_env.evaluate_v2(include_business_as_usual=False) result = BusinessAsUsualBaselineResult( env=baseline_env, kpis_v2=kpis_v2, episode=episode, time_step=target_time_step, ev_charge_target=ev_charge_target, ) env._business_as_usual_baseline_cache = {cache_key: result} return result
[docs] def clear(self): self.env._business_as_usual_baseline_cache = {}
def _new_sidecar_env(self) -> "CityLearnEnv": env = self.env schema = deepcopy(env.schema) if isinstance(schema, dict): schema['render'] = False schema['render_mode'] = 'none' schema['export_kpis_on_episode_end'] = False schema['debug_timing'] = False schema['metrics_log_interval'] = 0 source_buildings = list(getattr(env, '_all_buildings', None) or env.buildings) source_evs = list(getattr(env, '_all_electric_vehicles', None) or env.electric_vehicles) building_names: Optional[List[str]] = [building.name for building in source_buildings] if source_buildings else None ev_names: Optional[List[str]] = [ev.name for ev in source_evs] if source_evs else None # Per-building constructor overrides are lists in the evaluated env's building order, but # `buildings=` names load in schema order. Indices keep the given order, so each list entry # reaches the same building and the reference steps its buildings in the same order. building_selection = self._schema_indices(schema, building_names) tracker = env.episode_tracker start = int(getattr(tracker, 'episode_start_time_step', 0) or 0) end = int(getattr(tracker, 'episode_end_time_step', max(start, getattr(env, 'time_steps', 1) - 1)) or start) simulation_start, simulation_end = start, end solar_generation = (getattr(env, '_constructor_overrides', None) or {}).get('solar_generation') if self._autosizes_equipment(schema, building_names, solar_generation): # Autosizing (batteries, PV, heat pumps, storage) reads the whole loaded data window, so # loading only this episode sizes different equipment than the evaluated env. Load the # source's window instead; the one explicit split still restricts the run to the episode. simulation_start = int(getattr(tracker, 'simulation_start_time_step', start)) simulation_end = int(getattr(tracker, 'simulation_end_time_step', end)) # Follow the evaluated env's interface: robustness events can target entity tables # (EV, storage, PV) that the flat layout does not expose, so a flat reference would # reject a schema the evaluated env accepted. The BAU agent reads simulator state # directly, so the interface does not change its actions. requires_entity_interface = ( getattr(env, 'interface', 'flat') == 'entity' or getattr(env, 'topology_mode', None) == 'dynamic' or bool(getattr(getattr(env, '_demand_response_service', None), 'enabled', False)) ) baseline_env = env.__class__( schema, root_directory=getattr(env, 'root_directory', None), buildings=building_selection, electric_vehicles=ev_names, simulation_start_time_step=simulation_start, simulation_end_time_step=simulation_end, episode_time_steps=[(start, end)], rolling_episode_split=False, random_episode_split=False, seconds_per_time_step=float(getattr(env, 'seconds_per_time_step', 3600.0)), central_agent=True, random_seed=getattr(env, '_initialization_seed', env.random_seed), offline=getattr(env, 'offline', False), time_step_ratio=getattr(env, 'time_step_ratio', None), interface='entity' if requires_entity_interface else 'flat', topology_mode=getattr(env, 'topology_mode', None), render_mode='none', export_kpis_on_episode_end=False, ev_departure_within_tolerance=env.ev_departure_within_tolerance, ev_departure_service_tolerance=env.ev_departure_service_tolerance, check_observation_limits=False, physics_invariant_checks=bool(getattr(env, 'physics_invariant_checks', False)), # The effective setting, which a constructor override may have changed from the schema's. energy_provenance=bool(getattr(env, 'energy_provenance', True)), **deepcopy(getattr(env, '_constructor_overrides', {})), ) baseline_env._business_as_usual_sidecar = True return baseline_env @staticmethod def _autosizes_equipment(schema, building_names: Optional[List[str]], solar_generation=None) -> bool: """Whether a building the sidecar loads sizes a device from its data. Without autosizing, equipment does not depend on the loaded window, so the sidecar can load just the episode, which is much cheaper for long or fine-grained datasets. PV that the `solar_generation` constructor argument disables is not loaded, so it sizes nothing. `building_names` are in the evaluated env's order, which `solar_generation` lists follow. """ from citylearn.internal.loading_components import solar_generation_enabled from citylearn.utilities import parse_bool buildings = schema.get('buildings', {}) if isinstance(schema, dict) else {} for index, name in enumerate(buildings if building_names is None else building_names): config = buildings.get(name) if not isinstance(config, dict): return True # Unknown configuration: load the source's window to be safe. try: pv_loaded = solar_generation_enabled(solar_generation, index) except (IndexError, TypeError): pv_loaded = True # Unknown setting: count the PV, which loads the source's window. for device_name, device in config.items(): if not isinstance(device, dict) or (device_name == 'pv' and not pv_loaded): continue try: if parse_bool(device.get('autosize', False), default=False): return True except (TypeError, ValueError): return True return False @staticmethod def _schema_indices(schema, building_names: Optional[List[str]]): """Schema positions of `building_names` in their order, or the names if one is not in the schema.""" buildings = schema.get('buildings') if isinstance(schema, dict) else None if building_names is None or not isinstance(buildings, dict): return building_names positions = {name: i for i, name in enumerate(buildings)} if any(name not in positions for name in building_names): return building_names # The configuration check then reports what the reference lacks. return [positions[name] for name in building_names]