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) → dict[source]

Returns a data set’s schema.

Parameters:

name (str) – Name of data set.

Returns:

schema – Data set schema.

Return type:

dict

class citylearn.data.EnergySimulation(month: Iterable[int], hour: Iterable[int], day_type: Iterable[int], daylight_savings_status: Iterable[int], indoor_dry_bulb_temperature: Iterable[float], average_unmet_cooling_setpoint_difference: Iterable[float], indoor_relative_humidity: Iterable[float], non_shiftable_load: Iterable[float], dhw_demand: Iterable[float], cooling_demand: Iterable[float], heating_demand: Iterable[float], solar_generation: Iterable[float], occupant_count: Iterable[int] = None, indoor_dry_bulb_temperature_set_point: Iterable[int] = None, hvac_mode: Iterable[int] = None, power_outage: Iterable[int] = 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.

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

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

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

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

  • 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].

  • occupant_count (np.array) – 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) – Heat pump and auxilliary electric heating availability. If 0, both HVAC devices are unavailable (off), if 1, the heat pump is available for space cooling and if 2, the heat pump and auxilliary electric heating are available for space heating only. 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 (power_outage) – 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 (0) – 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.

  • 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.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.