citylearn.data module

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

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.DataSet[source]

Bases: object

CityLearn input data set and schema class.

static copy(name: str, destination_directory: Path | str = None)[source]

Copies an internally stored CityLearn dataset to a location of choice.

Parameters:

destination_directory (Union[Path, str], optional) – Target directory to copy data set files to. Copies to current directory if not specifed.

static get_names() → List[str][source]

Returns list of internally stored CityLearn datasets that are schema names and can be used to initialize citylearn.citylearn.CityLearnEnv.

Returns:

names – schema names

Return type:

List[str]

static get_schema(name: str) → Mapping[str, dict | float | str][source]

Returns a data set’s schema.

Parameters:

name (str) – Name of data set.

Returns:

schema – Data set schema.

Return type:

Mapping[str, Union[dict, float, 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_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)[source]

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.

  • 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_set_point (np.array) – Average building dry bulb temperature 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 about the indoor_dry_bulb_temperature_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 about the indoor_dry_bulb_temperature_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
static get_battery_sizing_data() → Mapping[str, float | str][source]

Reads and returns internally defined real world manufacturer models.

Returns:

data

Return type:

Mapping[str, Union[float, str]]

Notes

Data source: https://github.com/intelligent-environments-lab/CityLearn/tree/master/citylearn/data/misc/battery_choices.yaml.

static get_pv_sizing_data() → DataFrame[source]

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

Returns:

data

Return type:

pd.DataFrame

Notes

Data source: https://github.com/intelligent-environments-lab/CityLearn/tree/master/citylearn/data/misc/lbl-tracking_the_sun_res-pv.csv.

class citylearn.data.Pricing(electricity_pricing: Iterable[float], electricity_pricing_predicted_6h: Iterable[float], electricity_pricing_predicted_12h: Iterable[float], electricity_pricing_predicted_24h: Iterable[float], start_time_step: int = None, end_time_step: int = None)[source]

Bases: TimeSeriesData

Building pricing data class.

Parameters:

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

  • electricity_pricing_predicted_6h (np.array) – Electricity pricing 6 hours ahead prediction time series in [$/kWh].

  • electricity_pricing_predicted_12h (np.array) – Electricity pricing 12 hours ahead prediction time series in [$/kWh].

  • electricity_pricing_predicted_24h (np.array) – Electricity pricing 24 hours ahead prediction time series in [$/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.TimeSeriesData(variable: Iterable = None, start_time_step: int = None, end_time_step: int = None)[source]

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.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_6h: Iterable[float], outdoor_dry_bulb_temperature_predicted_12h: Iterable[float], outdoor_dry_bulb_temperature_predicted_24h: Iterable[float], outdoor_relative_humidity_predicted_6h: Iterable[float], outdoor_relative_humidity_predicted_12h: Iterable[float], outdoor_relative_humidity_predicted_24h: Iterable[float], diffuse_solar_irradiance_predicted_6h: Iterable[float], diffuse_solar_irradiance_predicted_12h: Iterable[float], diffuse_solar_irradiance_predicted_24h: Iterable[float], direct_solar_irradiance_predicted_6h: Iterable[float], direct_solar_irradiance_predicted_12h: Iterable[float], direct_solar_irradiance_predicted_24h: Iterable[float], start_time_step: int = None, end_time_step: int = None)[source]

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_6h (np.array) – Outdoor dry bulb temperature 6 hours ahead prediction time series in [C].

  • outdoor_dry_bulb_temperature_predicted_12h (np.array) – Outdoor dry bulb temperature 12 hours ahead prediction time series in [C].

  • outdoor_dry_bulb_temperature_predicted_24h (np.array) – Outdoor dry bulb temperature 24 hours ahead prediction time series in [C].

  • outdoor_relative_humidity_predicted_6h (np.array) – Outdoor relative humidity 6 hours ahead prediction time series in [%].

  • outdoor_relative_humidity_predicted_12h (np.array) – Outdoor relative humidity 12 hours ahead prediction time series in [%].

  • outdoor_relative_humidity_predicted_24h (np.array) – Outdoor relative humidity 24 hours ahead prediction time series in [%].

  • diffuse_solar_irradiance_predicted_6h (np.array) – Diffuse solar irradiance 6 hours ahead prediction time series in [W/m^2].

  • diffuse_solar_irradiance_predicted_12h (np.array) – Diffuse solar irradiance 12 hours ahead prediction time series in [W/m^2].

  • diffuse_solar_irradiance_predicted_24h (np.array) – Diffuse solar irradiance 24 hours ahead prediction time series in [W/m^2].

  • direct_solar_irradiance_predicted_6h (np.array) – Direct solar irradiance 6 hours ahead prediction time series in [W/m^2].

  • direct_solar_irradiance_predicted_12h (np.array) – Direct solar irradiance 12 hours ahead prediction time series in [W/m^2].

  • direct_solar_irradiance_predicted_24h (np.array) – Direct solar irradiance 24 hours ahead prediction time series in [W/m^2].

  • 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()[source]