citylearn.community_dataset module

Explicit physical and economic contracts for inventory-derived datasets.

Legacy schemas are unchanged. Prices are EUR/kWh and timeseries are indexed by absolute dataset time, including an episode’s start offset.

class citylearn.community_dataset.InventoryBattery(max_charge_kw, max_discharge_kw, min_soc=0.0, max_soc=1.0, charging_efficiency=1.0, discharging_efficiency=1.0, **kwargs)

Bases: Battery

Battery with declared asymmetric powers, SOC range and efficiencies.

charge(energy)

Charges or discharges storage with respect to specified energy while considering capacity degradation and soc_init limitations, losses to the environment quantified by efficiency, power_efficiency_curve and capacity_power_curve.

Parameters:

energy (float) – Energy to charge if (+) or discharge if (-) in [kWh].

get_current_efficiency(power)

Get technical efficiency while considering power_efficiency_curve limitations.

Returns:

efficiency – Technical efficiency.

Return type:

float

get_max_input_power(energy_init=None)

Get maximum input power while considering capacity_power_curve limitations.

Returns:

max_input_power – Maximum amount of power that the storage unit can use to charge [kW].

Return type:

float

get_max_output_power(energy_init=None)

Get maximum output power while considering capacity_power_curve limitations if defined otherwise, returns nominal_power.

Returns:

max_output_power – Maximum amount of power that the storage unit can output [kW].

Return type:

float

get_metadata()

Returns general static information.

class citylearn.community_dataset.InventoryBuilding(energy_simulation: EnergySimulation, weather: Weather, observation_metadata: Mapping[str, bool], action_metadata: Mapping[str, bool], episode_tracker: EpisodeTracker, carbon_intensity: CarbonIntensity = None, pricing: Pricing = None, dhw_storage: StorageTank = None, cooling_storage: StorageTank = None, heating_storage: StorageTank = None, electrical_storage: Battery = None, dhw_device: HeatPump | ElectricHeater = None, cooling_device: HeatPump = None, heating_device: HeatPump | ElectricHeater = None, pv: PV = None, name: str = None, maximum_temperature_delta: float = None, observation_space_limit_delta: float = None, demand_observation_limit_factor: float = None, simulate_power_outage: bool = None, stochastic_power_outage: bool = None, stochastic_power_outage_model: PowerOutage = None, electric_vehicle_chargers: List[Charger] = None, time_step_ratio: int = None, deferrable_appliances: List[DeferrableAppliance] = None, washing_machines: List[WashingMachine] = None, escalators: List[Escalator] = None, **kwargs: Any)

Bases: Building

Versioned loader for inventory scenarios; older runtimes fail explicitly.

class citylearn.community_dataset.InventoryEVBuilding(energy_simulation: EnergySimulation, weather: Weather, observation_metadata: Mapping[str, bool], action_metadata: Mapping[str, bool], episode_tracker: EpisodeTracker, carbon_intensity: CarbonIntensity = None, pricing: Pricing = None, dhw_storage: StorageTank = None, cooling_storage: StorageTank = None, heating_storage: StorageTank = None, electrical_storage: Battery = None, dhw_device: HeatPump | ElectricHeater = None, cooling_device: HeatPump = None, heating_device: HeatPump | ElectricHeater = None, pv: PV = None, name: str = None, maximum_temperature_delta: float = None, observation_space_limit_delta: float = None, demand_observation_limit_factor: float = None, simulate_power_outage: bool = None, stochastic_power_outage: bool = None, stochastic_power_outage_model: PowerOutage = None, electric_vehicle_chargers: List[Charger] = None, time_step_ratio: int = None, deferrable_appliances: List[DeferrableAppliance] = None, washing_machines: List[WashingMachine] = None, escalators: List[Escalator] = None, **kwargs: Any)

Bases: InventoryBuilding

Requires the EV battery loader contract introduced in version 1.8.2.

class citylearn.community_dataset.RuntimeEVBuilding(energy_simulation: EnergySimulation, weather: Weather, observation_metadata: Mapping[str, bool], action_metadata: Mapping[str, bool], episode_tracker: EpisodeTracker, carbon_intensity: CarbonIntensity = None, pricing: Pricing = None, dhw_storage: StorageTank = None, cooling_storage: StorageTank = None, heating_storage: StorageTank = None, electrical_storage: Battery = None, dhw_device: HeatPump | ElectricHeater = None, cooling_device: HeatPump = None, heating_device: HeatPump | ElectricHeater = None, pv: PV = None, name: str = None, maximum_temperature_delta: float = None, observation_space_limit_delta: float = None, demand_observation_limit_factor: float = None, simulate_power_outage: bool = None, stochastic_power_outage: bool = None, stochastic_power_outage_model: PowerOutage = None, electric_vehicle_chargers: List[Charger] = None, time_step_ratio: int = None, deferrable_appliances: List[DeferrableAppliance] = None, washing_machines: List[WashingMachine] = None, escalators: List[Escalator] = None, **kwargs: Any)

Bases: InventoryEVBuilding

Runtime EV datasets require arrival observations fixed in version 1.8.3.

citylearn.community_dataset.configure_tariffs(env, config)

Load portable per-building tariffs once; invalid explicit data fails closed.

citylearn.community_dataset.settlement_prices(env, name, time_step, grid_import_price)