citylearn.data module

class citylearn.data.CarbonIntensity(carbon_intensity: Iterable[float], start_time_step: int = None, end_time_step: int = None, noise_std: float = 0.0)

Bases: TimeSeriesData

Building carbon_intensity data class.

Parameters:

• carbon_intensity (np.array) – Grid carbon emission rate time series in [kg_co2/kWh].

• start_time_step (int, optional) – Time step to start reading variables.

• end_time_step (int, optional) – Time step to end reading variables.

class citylearn.data.ChargerSimulation(electric_vehicle_charger_state: Iterable[int], electric_vehicle_id: Iterable[str], electric_vehicle_battery_capacity_khw: Iterable[float], current_soc: Iterable[float], electric_vehicle_departure_time: Iterable[float], electric_vehicle_required_soc_departure: Iterable[float], electric_vehicle_estimated_arrival_time: Iterable[float], electric_vehicle_estimated_soc_arrival: Iterable[float], start_time_step: int = None, end_time_step: int = None, noise_std: float = 1.0)

Bases: TimeSeriesData

Charger-centric electric vehicle simulation data class.

This class models the charging schedule of electric vehicles from the perspective of a specific charger, with one entry per timestep indicating the state of a connected or incoming EV.

electric_vehicle_charger_state

State of the electric vehicle:

1: ‘Parked, plugged in, and ready to charge’ 2: ‘Incoming to a charger’ 3: ‘Commuting (vehicle is away)’

Type:

np.array

electric_vehicle_id

Identifier for the electric vehicle.

Type:

np.array

electric_vehicle_battery_capacity_kwh

Battery capacity of the vehicle (in kilowatt-hours).

Type:

np.array

current_soc

Current state-of-charge of the EV battery at the charger (normalized [0, 1]). This is calculated from the raw kWh value divided by capacity.

Type:

np.array

electric_vehicle_departure_time

Number of time steps expected until the EV departs from the charger (only for state 1). Defaults to -1 when not present.

Type:

np.array

electric_vehicle_required_soc_departure

Target SOC percentage required for the EV at departure time (only for state 1), normalized to the [0, 1] range and with added Gaussian noise if provided. Defaults to -0.1 when not present.

Type:

np.array

electric_vehicle_estimated_arrival_time

Number of time steps expected until the EV arrives at the charger (only for state 2). Defaults to -1 when not present.

Type:

np.array

electric_vehicle_estimated_soc_arrival

Estimated SOC percentage at the time of arrival to the charger (only for state 2), normalized to the [0, 1] range and with optional Gaussian noise. Defaults to -0.1 when not present.

Type:

np.array

class citylearn.data.DataSet(github_account: str = None, repository: str = None, tag: str = None, datasets_path: str = None, misc_path: str = None, logging_level: int = None)

Bases: object

CityLearn input data set and schema class.

BATTERY_CHOICES_FILENAME = 'battery_choices.yaml'

DEFAULT_CACHE_DIRECTORY = '/home/runner/.cache/citylearn/v2.4.3'

GITHUB_ACCOUNT = 'intelligent-environments-lab'

GITHUB_API_CONTENT_URL = 'https://api.github.com/repos/intelligent-environments-lab/CityLearn/contents'

PV_CHOICES_FILENAME = 'lbl-tracking_the_sun-res-pv.csv'

REPOSITORY_DATA_DATASETS_PATH = 'data/datasets'

REPOSITORY_DATA_MISC_PATH = 'data/misc'

REPOSITORY_DATA_PATH = 'data'

REPOSITORY_NAME = 'CityLearn'

REPOSITORY_TAG = 'v2.4.3'

property cache_directory: Path | str

clear_cache()

property datasets_path: str

get_battery_sizing_data() → Mapping[str, float | str]

Reads and returns internally defined real world manufacturer models.

Returns:

data

Return type:

Mapping[str, Union[float, str]]

get_dataset(name: str, directory: Path | str = None) → str

get_dataset_names() → List[str]

get_github_contents(path: str = None) → List[Mapping[str, Any]]

get_pv_sizing_data() → DataFrame

Reads and returns LBNL’’s Tracking The Sun dataset that has been prefilered for completeness.

Returns:

data

Return type:

pd.DataFrame

static get_requests_session(**kwargs) → Session

get_schema(name: str) → dict

property github_account: str

property logging_level: int

property misc_path: str

property repository: str

property tag: str

class citylearn.data.EnergySimulation(month: Iterable[int], hour: Iterable[int], day_type: Iterable[int], indoor_dry_bulb_temperature: Iterable[float], non_shiftable_load: Iterable[float], dhw_demand: Iterable[float], cooling_demand: Iterable[float], heating_demand: Iterable[float], solar_generation: Iterable[float], daylight_savings_status: Iterable[int] = None, average_unmet_cooling_setpoint_difference: Iterable[float] = None, indoor_relative_humidity: Iterable[float] = None, occupant_count: Iterable[int] = None, indoor_dry_bulb_temperature_cooling_set_point: Iterable[int] = None, indoor_dry_bulb_temperature_heating_set_point: Iterable[int] = None, hvac_mode: Iterable[int] = None, power_outage: Iterable[int] = None, comfort_band: Iterable[float] = None, start_time_step: int = None, end_time_step: int = None, seconds_per_time_step: int = None, minutes: Iterable[int] = None, time_step_ratios: list[int] = [], noise_std=0.0)

Bases: TimeSeriesData

Building energy_simulation data class.

Parameters:

• month (np.array) – Month time series value ranging from 1 - 12.

• hour (np.array) – Hour time series value ranging from 1 - 24.

• minutes (np.array) – Minutes time series value ranging from 0 - 60.

• day_type (np.array) – Numeric day of week time series ranging from 1 - 8 where 1 - 7 is Monday - Sunday and 8 is reserved for special days e.g. holiday.

• indoor_dry_bulb_temperature (np.array) – Average building dry bulb temperature time series in [C].

• non_shiftable_load (np.array) – Total building non-shiftable plug and equipment loads time series in [kWh].

• dhw_demand (np.array) – Total building domestic hot water demand time series in [kWh].

• cooling_demand (np.array) – Total building space cooling demand time series in [kWh].

• heating_demand (np.array) – Total building space heating demand time series in [kWh].

• solar_generation (np.array) – Inverter output per 1 kW of PV system time series in [W/kW].

• daylight_savings_status (np.array, optional) – Daylight saving status time series signal of 0 or 1 indicating inactive or active daylight saving respectively.

• average_unmet_cooling_setpoint_difference (np.array, optional) – Average difference between indoor_dry_bulb_temperature and cooling temperature setpoints time series in [C].

• indoor_relative_humidity (np.array, optional) – Average building relative humidity time series in [%].

• occupant_count (np.array, optional) – Building occupant count time series in [people].

• indoor_dry_bulb_temperature_cooling_set_point (np.array) – Average building dry bulb temperature cooling set point time series in [C].

• indoor_dry_bulb_temperature_heating_set_point (np.array) – Average building dry bulb temperature heating set point time series in [C].

• hvac_mode (np.array, default: 1) – Cooling and heating device availability. If 0, both HVAC devices are unavailable (off), if 1, the cooling device is available for space cooling and if 2, the heating device is available for space heating only. Automatic (auto) mode is 3 and allows for either cooling or heating depending on the control action. The default is to set the mode to cooling at all times. The HVAC devices are always available for cooling and heating storage charging irrespective of the hvac mode.

• np.array (comfort_band) – Signal for power outage. If 0, there is no outage and building can draw energy from grid. If 1, there is a power outage and building can only use its energy resources to meet loads.

• default (2) – Signal for power outage. If 0, there is no outage and building can draw energy from grid. If 1, there is a power outage and building can only use its energy resources to meet loads.

• np.array – Occupant comfort band above the indoor_dry_bulb_temperature_cooling_set_point and below the indoor_dry_bulb_temperature_heating_set_point [C]. The value is added to and subtracted from the set point to set the upper and lower bounds of comfort bound.

• default – Occupant comfort band above the indoor_dry_bulb_temperature_cooling_set_point and below the indoor_dry_bulb_temperature_heating_set_point [C]. The value is added to and subtracted from the set point to set the upper and lower bounds of comfort bound.

• start_time_step (int, optional) – Time step to start reading variables.

• end_time_step (int, optional) – Time step to end reading variables.

DEFUALT_COMFORT_BAND = 2.0

property time_step_ratios

Getter for the time_step_ratio variable.

class citylearn.data.LogisticRegressionOccupantParameters(a_increase: Iterable[float], b_increase: Iterable[float], a_decrease: Iterable[float], b_decrease: Iterable[float], start_time_step: int = None, end_time_step: int = None)

Bases: TimeSeriesData

class citylearn.data.Pricing(electricity_pricing: Iterable[float], electricity_pricing_predicted_1: Iterable[float], electricity_pricing_predicted_2: Iterable[float], electricity_pricing_predicted_3: Iterable[float], start_time_step: int = None, end_time_step: int = None, noise_std: float = 0.0)

Bases: TimeSeriesData

Building pricing data class.

Parameters:

• electricity_pricing (np.array) – Electricity pricing time series in [$/kWh].

• electricity_pricing_predicted_1 (np.array) – Electricity pricing n hours ahead prediction time series in [$/kWh]. n can be any number of hours and is typically 1 or 6 hours in existing datasets.

• electricity_pricing_predicted_2 (np.array) – Electricity pricing n hours ahead prediction time series in [$/kWh]. n can be any number of hours and is typically 2 or 12 hours in existing datasets.

• electricity_pricing_predicted_3 (np.array) – Electricity pricing n hours ahead prediction time series in [$/kWh]. n can be any number of hours and is typically 3 or 24 hours in existing datasets.

• start_time_step (int, optional) – Time step to start reading variables.

• end_time_step (int, optional) – Time step to end reading variables.

as_dict(time_step) → dict

Return a dictionary representation of the current pricing data.

Returns:

Dictionary containing current electricity pricing and predictions, with keys matching the class attribute names.

Return type:

dict

class citylearn.data.TimeSeriesData(variable: Iterable = None, start_time_step: int = None, end_time_step: int = None)

Bases: object

Generic time series data class.

Parameters:

• variable (np.array, optional) – A generic time series variable.

• start_time_step (int, optional) – Time step to start reading variables.

• end_time_step (int, optional) – Time step to end reading variables.

class citylearn.data.WashingMachineSimulation(day_type: Iterable[int], hour: Iterable[int], wm_start_time_step: Iterable[int], wm_end_time_step: Iterable[int], load_profile: Iterable[str], start: int = None, end: int = None)

Bases: TimeSeriesData

Washing Machine Simulation data class.

day_type

Type of the day (e.g., weekday/weekend).

Type:

np.array

hour

Hour of the day when the washing machine is scheduled.

Type:

np.array

start_time_step

Start time step of the washing machine usage.

Type:

np.array

end_time_step

End time step of the washing machine usage.

Type:

np.array

load_profile

List of power consumption values during the washing machine’s cycle.

Type:

np.array

class citylearn.data.Weather(outdoor_dry_bulb_temperature: Iterable[float], outdoor_relative_humidity: Iterable[float], diffuse_solar_irradiance: Iterable[float], direct_solar_irradiance: Iterable[float], outdoor_dry_bulb_temperature_predicted_1: Iterable[float], outdoor_dry_bulb_temperature_predicted_2: Iterable[float], outdoor_dry_bulb_temperature_predicted_3: Iterable[float], outdoor_relative_humidity_predicted_1: Iterable[float], outdoor_relative_humidity_predicted_2: Iterable[float], outdoor_relative_humidity_predicted_3: Iterable[float], diffuse_solar_irradiance_predicted_1: Iterable[float], diffuse_solar_irradiance_predicted_2: Iterable[float], diffuse_solar_irradiance_predicted_3: Iterable[float], direct_solar_irradiance_predicted_1: Iterable[float], direct_solar_irradiance_predicted_2: Iterable[float], direct_solar_irradiance_predicted_3: Iterable[float], start_time_step: int = None, end_time_step: int = None, noise_std: float = 0.0)

Bases: TimeSeriesData

Building weather data class.

Parameters:

• outdoor_dry_bulb_temperature (np.array) – Outdoor dry bulb temperature time series in [C].

• outdoor_relative_humidity (np.array) – Outdoor relative humidity time series in [%].

• diffuse_solar_irradiance (np.array) – Diffuse solar irradiance time series in [W/m^2].

• direct_solar_irradiance (np.array) – Direct solar irradiance time series in [W/m^2].

• outdoor_dry_bulb_temperature_predicted_1 (np.array) – Outdoor dry bulb temperature n hours ahead prediction time series in [C]. n can be any number of hours and is typically 6 hours in existing datasets.

• outdoor_dry_bulb_temperature_predicted_2 (np.array) – Outdoor dry bulb temperature n hours ahead prediction time series in [C]. n can be any number of hours and is typically 12 hours in existing datasets.

• outdoor_dry_bulb_temperature_predicted_3 (np.array) – Outdoor dry bulb temperature n hours ahead prediction time series in [C]. n can be any number of hours and is typically 24 hours in existing datasets.

• outdoor_relative_humidity_predicted_1 (np.array) – Outdoor relative humidity n hours ahead prediction time series in [%]. n can be any number of hours and is typically 6 hours in existing datasets.

• outdoor_relative_humidity_predicted_2 (np.array) – Outdoor relative humidity n hours ahead prediction time series in [%]. n can be any number of hours and is typically 12 hours in existing datasets.

• outdoor_relative_humidity_predicted_3 (np.array) – Outdoor relative humidity n hours ahead prediction time series in [%]. n can be any number of hours and is typically 24 hours in existing datasets.

• diffuse_solar_irradiance_predicted_1 (np.array) – Diffuse solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 6 hours in existing datasets.

• diffuse_solar_irradiance_predicted_2 (np.array) – Diffuse solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 12 hours in existing datasets.

• diffuse_solar_irradiance_predicted_3 (np.array) – Diffuse solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 24 hours in existing datasets.

• direct_solar_irradiance_predicted_1 (np.array) – Direct solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 6 hours in existing datasets.

• direct_solar_irradiance_predicted_2 (np.array) – Direct solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 12 hours in existing datasets.

• direct_solar_irradiance_predicted_3 (np.array) – Direct solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 24 hours in existing datasets.

• start_time_step (int, optional) – Time step to start reading variables.

• end_time_step (int, optional) – Time step to end reading variables.

citylearn.data.get_settings()