Simulators

The following simulators are ready to use for simulations .

Identity Cards

An ID cards system simplifies the usage of simulators.

Each simulator is given different types of parameters:

• Params: the parameters of input for the __init__().

• Data: the loading methods required from the Dataloader given in the data param.

• Step input: the arguments of the step() method of the simulator.

• Output: the get methods available.

• Step size: the time between two steps.

With these identity cards, the usage of the simulators and the datasets is made simpler. The possible values for each parameters are available at Cards Documentation.

Activity simulators

Activity simulators generate patterns of the residents occupations during the days.

class demod.simulators.crest_simulators.Crest4StatesModel(n_households, data=<demod.datasets.CREST.loader.Crest object>, start_datetime=datetime.datetime(2014, 1, 1, 0, 0), **kwargs)

Simulates the whole population as in CREST.

This simulates households based on the 4 States model of McKenna [McKenna2016]. You can see more information at 4-states occupancy simulator. The simulator distinguish only the number of residents from 1 to 5 and between weekends and weekdays. It samples randomly how many households belong to which number of residents based on the pdf of the real households.

load_population_subgroups() must be implemented for population_type = ‘resident_number’

Params

n_households data start_datetime population_sampling_algo logger

Data

load_tpm() load_population_subgroups()

Step input

None

Output

get_occupancy() get_active_occupancy() get_thermal_gains()

Step size

10 Minutes

class demod.simulators.sparse_simulators.SparseTransitStatesSimulator(n_households, subgroup_kwargs, data=<demod.datasets.GermanTOU.loader.GTOU object>, **kwargs)

Simulates the Occupancy and Activity based on Transit.

The states are simulated as household states using the number of residents doing an activity. Replaces the ‘at home’ state of a 4-states occupancy simulator by ‘HWH’ and ‘HOH’, which represent transit activity for a work activity (home-work-home) or an other activity (home-other-home). See Transit occupancy simulator. You can access the number of persons in HOH by using self.get_n_doing_activity('HOH'). data must be initialized with ‘Sparse9States’ as activity_type.

Params

n_households subgroup data logger time_aware start_datetime

Data

load_sparse_tpm()

Step input

None.

Output

get_occupancy() get_active_occupancy() get_thermal_gains() get_n_doing_activity()

Step size

10 Minutes.

class demod.simulators.sparse_simulators.SubgroupsActivitySimulator(subgroups_list, n_households_list, subsimulator=<class 'demod.simulators.sparse_simulators.SparseTransitStatesSimulator'>, logger=None, **kwargs)

Multisimulator for Activity simulators.

Simulates different subsimulators of the activity.

subgroups_list and n_households_list can be loaded from a dataset through load_population_subgroups() and sample_population().

Params

subgroups_list n_households_list subsimulator data logger time_aware start_datetime

Data

load_sparse_tpm()

Step input

None.

Output

get_occupancy() get_active_occupancy() get_thermal_gains() get_n_doing_activity()

Step size

10 Minutes.

class demod.simulators.activity_simulators.SubgroupsIndividualsActivitySimulator(subgroups_list, n_households_list, subsimulator=<class 'demod.simulators.activity_simulators.MarkovChain1rstOrder'>, data=<demod.datasets.GermanTOU.loader.GTOU object>, use_week_ends_days=False, use_week_sat_sun=False, use_7days=False, use_quarters=False, **kwargs)

Multisimulator for simulating households activity based on individuals.

Simulates different subsimulators of the activity of the people. Then groups them into households. Keeps track of the time and when to updates the internal simulators. Handles the data flows from the dataset and the subsimulators.

Note that it does not take into account the correlation between the residents, as each resident is simulated independently of the others.

subgroups_list and n_households_list can be loaded from a dataset through load_population_subgroups() and sample_population().

You can simply pass the subsimulator class that you want to implement, as well as specifiying how many households of each subgroups should be simulated. At the moment, only MarkovChain1rstOrder and SemiMarkovSimulator are accepted as subsimulators.

If at least one of the three parameters use_week_ends_days use_7days use_quarters is True, the simulator will check if it should update its parameters every simulated day.

This simulator only simulates the activities and how many persons are in it. If you want to simulate occupancy, you need to override the following methods : get_occupancy() get_active_occupancy() get_thermal_gains() or to have ‘away’ and ‘sleeping’ activites in the dataset.

Params

subgroups_list n_households_list subsimulator data use_week_ends_days use_week_sat_sun use_7days use_quarters start_datetime logger

Data

refresh_time load_tpm() or load_tpm_with_duration()

Step input

None.

Output

get_n_doing_activity() get_activity_states() get_occupancy() get_active_occupancy()

Step size

10 Minutes.

Weather simulators

It is possible to either use real weather data or to simulate the weather.

class demod.simulators.weather_simulators.CrestIrradianceSimulator(data='CREST', initial_clearness=0.99, start_datetime=datetime.datetime(2014, 1, 1, 0, 0), **kwargs)

Irradiance simulator from CREST.

Simulates the irradiance, based on a markov transition probabilies model for the irradiance during the day.

Params

data start_datetime logger initial_clearness

Data

load_clearness_tpms() load_geographic_data()

Step input

None

Output

get_irradiance()

Step size

1 Minute

class demod.simulators.weather_simulators.CrestClimateSimulator(data='CREST', start_datetime=datetime.datetime(2014, 1, 1, 0, 0), initial_clearness=0.99, **kwargs)

Climate simulator from CREST.

Simulates the climate, based on CrestIrradianceSimulator, and an ARMA model for the temperature.

Params

data start_datetime logger initial_clearness

Data

load_clearness_tpms() load_geographic_data() load_temperatures_arma()

Step input

None

Output

get_irradiance() get_outside_temperature()

Step size

1 Minute

class demod.simulators.weather_simulators.RealClimate(data='Germany', start_datetime=datetime.datetime(1980, 1, 1, 0, 0), **kwargs)

Simulator that outputs real climate data.

Iterates over the historical climate data.

Note

In a future update this could create getters and handle all the data names loaded by load_historical_climate_data().

Params

data start_datetime logger

Data

load_historical_climate_data()

Step input

None

Output

get_irradiance() get_outside_temperature()

Step size

data. step_size

class demod.simulators.weather_simulators.RealInterpolatedClimate(data='Germany', start_datetime=datetime.datetime(1980, 1, 1, 0, 0), interpolation_kind='linear', **kwargs)

Simulator that interpolated values from real climate data.

scipy will be required to use this simulator.

Params

step_size data interpolation_kind start_datetime logger

Data

load_historical_climate_data()

Step input

None

Output

get_irradiance() get_outside_temperature()

Step size

Any. Set in Params.

Lighting simulators

class demod.simulators.lighting_simulators.FisherLightingSimulator(n_households, data='Germany', initial_active_occupancy=None, initial_irradiance=None, **kwargs)

Lighting simulator as described by [Fisher2015].

Simulates the electric consumption of lighting using a simple formula:

where is the active_occupancy , is a constant representing the Power used by a single person. and are the irradiance thresholds for lighting demand and is the current irradiance

Params

n_households data logger initial_active_occupancy initial_irradiance

Data

load_fisher_lighting()

Step input

active_occupancy irradiance

Output

get_energy_consumption()

Step size

Any.

class demod.simulators.lighting_simulators.CrestLightingSimulator(n_households, data='CREST', initialization_method='off', bulbs_sampling_algo='config', **kwargs)

Lighting simulator as proposed by CREST [Richardson2009] .

Params

n_households data initialization_method bulbs_sampling_algo logger

Data

load_crest_lighting() Optionals on bulbs_sampling_algo (load_bulbs() load_installed_bulbs_stats() load_bulbs_config())

Step input

active_occupancy irradiance

Output

get_energy_consumption()

Step size

Any.

CrestLightingSimulator.sample_bulbs_configuration(bulbs_sampling_algo)

Samples the configuration of the light bulbs in the house.

The available algorithms are:

• ‘randn’:

  samples the bulbs from a random distribution, based on values obtained with load_bulbs() and load_installed_bulbs_stats()

• ‘config’:

  samples the bulbs randomly based on diffrent configuration for the full house, obtained with load_bulbs_config()

Parameters

bulbs_sampling_algo (str) – The algorithm to use for sampling.

Raises

ValueError – If the algo is not known.

Returns

light_configs, The bulbs power consumption for each household.

Return type

numpy.ndarray

Appliances simulators

Appliances simulator simulate the electricity consumption of different house appliances.

class demod.simulators.appliance_simulators.OccupancyApplianceSimulator(subgroups_list, n_households_list, data=<demod.datasets.Germany.loader.GermanDataHerus object>, step_size=None, initial_active_occupancy=None, equipped_sampling_algo='subgroup', **kwargs)

Simulator for appliances based on active occupancy.

It uses

• the simulated household active occupancy

• the activity profiles of different subgroups

• a target electric consumption value

to compute the switch on probability of each appliance.

This simulators is a modification of the original CREST Appliance simulation. Its improvements are mainly the compatibility for any subgroup activity profiles, the ownership of the appliance that can be subgroup dependant, and also the customization of the appliances in the dataset.

The data loading methods determine which appliances should be loaded and their characteristics.

FOR FUTURE IMPLEMENTATION The target consumption should vary depending on the subgroups. Currently it is the same for all subgroups, as we have no such data.

FOR FUTURE IMPLEMENTATION Switchon probabilites should be compuuted for each subgroup and appliance instead of being computed in the excell file as in CREST.

Params

subgroups_list n_households_list data logger start_datetime equipped_sampling_algo real_profiles_algo initial_active_occupancy

Data

load_activity_probability_profiles() load_appliance_dict()

Data optional

load_appliance_ownership_dict() load_real_profiles_dict()

Step input

active_occupancy

Output

get_power_demand() get_current_usage() get_current_power_consumptions() get_current_water_consumptions() get_thermal_gains() get_dhw_heating_demand()

Step size

1 Minute.

class demod.simulators.appliance_simulators.SubgroupApplianceSimulator(*args, **kwargs)

Deprecated in versions > 0.1.

Use OccupancyApplianceSimulator instead.

class demod.simulators.appliance_simulators.ActivityApplianceSimulator(n_households, initial_activities_dict, data=<demod.datasets.Germany.loader.GermanDataHerus object>, subgroups_list=None, n_households_list=None, **kwargs)

Appliance simulator based on residents activities.

Turns the appliances on and keeps them activated while residents are performing corresponding activites. The appliances are always ON while the activity is performed in the household. Appliances that are turned ON and OFF randomly depending on the activity can be simulated by ProbabiliticActivityAppliancesSimulator

Params

subgroups_list n_households_list data logger equipped_sampling_algo real_profiles_algo initial_activities_dict

Data

load_appliance_dict()

Data optional

load_appliance_ownership_dict() load_real_profiles_dict()

Step input

activities_dict

Output

get_power_demand() get_current_usage() get_current_power_consumptions() get_current_water_consumptions() get_thermal_gains() get_dhw_heating_demand()

Step size

From the dataset. (For the real profiles)

class demod.simulators.appliance_simulators.ProbabiliticActivityAppliancesSimulator(n_households, initial_activities_dict, data=<demod.datasets.Germany.loader.GermanDataHerus object>, subgroups_list=None, n_households_list=None, **kwargs)

Appliance simulator based on residents activities.

Similar to ActivityApplianceSimulator but adds a probability that appliances are switched on or off, based on the target_cycle_year of the appliances_dict. Turns the appliances during the time its corresponding activity is performed, or during the duration sampled.

The simulator needs some data input from the appliance usage to compute the probability of switching on when the activity occurs.

Note

This methods allows only for a single use per day of the probabilistic appliances.

Params

subgroups_list n_households_list data logger equipped_sampling_algo initial_activities_dict

Data

load_appliance_dict() load_yearly_target_switchons() load_activity_probabilities() load_daily_activity_starts()

Data optional

load_appliance_ownership_dict() load_real_profiles_dict()

Step input

activities_dict

Output

get_power_demand() get_current_usage() get_current_power_consumptions() get_current_water_consumptions() get_thermal_gains() get_dhw_heating_demand()

Step size

From the dataset.

Heating simulators

class demod.simulators.heating_simulators.FiveModulesHeatingSimulator(n_households, initial_outside_temperature, heatdemand_algo='heat_max_emmiters', data=<demod.datasets.Germany.loader.GermanDataHerus object>, step_size=datetime.timedelta(seconds=60), **kwargs)

Simulator for the heat load using 5 components.

It simulates the energy consumption of an household required for heating. The five components simulated:

• The heating system (boiler, heat pump, …)

• The controls of the heating system.

• The heat demand of the house.

• The thermostats of different components

• The temperatures of the building components.

The implementation is based on CREST model, with a simplification of the thermostats and controls.

This simulator is also compatible with external simulated components.

• External thermostat

  the desired indoor temperature can be passed in the step method through external_target_temperature

• An external heating system

  it can pass its heat outputs through set_external_heating_system() and in the step method: external_heat_outputs external_dhw_outputs external_sh_outputs If external heat outputs are given, the heat load simulator will return 0 power demand for those households.

• Hot water storage cylinder

  if the heating system also has an external hot water storage cylinder, it can communicate using external_cylinder_temperature

Params

n_households initial_outside_temperature heatdemand_algo data step_size logger

Data

load_heating_system_dict() load_thermostat_dict() load_buildings_dict()

Step input

outside_temperature irradiance dhw_heating_demand occupancy_thermal_gains lighting_thermal_gains appliances_thermal_gains

Optional step input

external_target_temperature external_heat_outputs external_dhw_outputs external_sh_outputs external_cylinder_temperature

Output

get_room_temperature() get_total_heat_demand() get_dhw_demand() get_sh_demand() get_power_demand() get_controls()

Step size

Any.

Heating Components

Heating simulators can be splitted into different heating components.

class demod.simulators.heating_simulators.BuildingThermalDynamics(n_households, heating_system, initial_outside_temperature, step_size=datetime.timedelta(seconds=60), target_temperatures=None, data=<demod.datasets.Germany.loader.GermanDataHerus object>, **kwargs)

Simulator for the buildling thermal dynamics.

It simulates the energy flows between different house components. The room, the heating system, the walls, the outside. Based on the current temperatures, at each step it updates the temperature based on energy flows. To compute the energy flows, it takes information from the climate and from the heat gains inside the house at each step.

Params

n_households data heating_system initial_outside_temperature step_size target_temperatures logger

Data

load_buildings_dict()

Step input

outside_temperature irradiance dhw_heating_demand occupancy_thermal_gains lighting_thermal_gains appliances_thermal_gains heat_outputs

Output

get_temperatures()

Step size

Any.

class demod.simulators.heating_simulators.Thermostats(n_households, initial_temperatures=None, data=<demod.datasets.Germany.loader.GermanDataHerus object>, **kwargs)

Simulator for the thermostats of the house.

Simulates the state of different thermostats (can be ON or OFF = True or False). Thermostat control the temperature of different component. They are switched to on once the temperature of a component is below its target_temperature minus a dead_band. Components:

• cylinder

• emitters

• interior (room temperature)

Params

n_households data initial_temperatures logger

Data

load_thermostat_dict()

Step input

temperatures

Optional step input

target_temperatures

Output

get_thermostat_states() get_target_temperatures()

Step size

Any.

Note

A future implementation could make it any_component friendly. It could be useful to simulate multiple rooms for example.

class demod.simulators.heating_simulators.HeatDemand(n_households, heating_system, building, step_size=datetime.timedelta(seconds=60), heatdemand_algo='heat_max_emmiters', deadbands={'emitter': 5, 'hot_water': 5, 'space_heating': 1}, **kwargs)

Simulator for the heat demand of the households.

It computes the heat demand for both: domestic hot water and space heating.

There exist different algorithm for computing the heat demand.

The hot water demand is calculate based on dhw_heating_demand and also accounts for losses in the hot water cylinder. It also aims at keeping the cylinder hot.

Params

n_households heating_system building step_size logger heatdemand_algo

Data

None

Step input

temperatures target_temperatures dhw_heating_demand outside_temperature

Output

get_heat_demand()

Step size

Any.

class demod.simulators.heating_simulators.SystemControls(n_households, is_combi_boiler=None, **kwargs)

Simulator for the controls of the heating system.

It checks which controls should be sent to the HeatingSystem, based on the heat demand and on the thermostats.

It can handle combi boilers, which means that the boiler does not stay on to keep the cylinder at a high temperature.

Params

n_households is_combi_boiler logger

Data

None

Step input

dhw_heating_demand thermostat_states has_external_cylinder

Output

get_controls()

Step size

Any.

is_combi_boiler

Specifies whether the heating system is a combi boiler or not. Combi boiler don’t maintain the hot water cylinder to a high temperature and produce dhw only on demand.

Type

numpy.ndarray

class demod.simulators.heating_simulators.HeatingSystem(n_households, data=<demod.datasets.Germany.loader.GermanDataHerus object>, initial_controls=None, initial_heat_demand=None, **kwargs)

Simulator for the heating system.

It simulates the consumption of the heating system to provide requested heat data.

Params

n_households data logger initial_controls initial_heat_demand

Data

load_heating_system_dict()

Step input

heating_controls heat_demand

Output

get_fuel_consumptions() get_power_demand() get_energy_consumption() get_heat_outputs()

Step size

Any.

Maybe add external cylinder in the future ???

Variable Thermostats

class demod.simulators.heating_simulators.VariableThermostatTemperatureSimulator(n_households, initial_occupancy, initial_act_occ, start_datetime, *args, **kwargs)

Simulator for variable room thermostats.

Based on the Living lab study by [Sovacool2020] that shows 6 different kinds of heating patterns.

• Cool Conservers, Often adjust temperature to try and cut bills

• Steady and Savvy, Rarely adjust their heating as they are fine with 18-20c

• Hot and Cold Fluctuators, Often adjust temperature to get comfortable

• On-Demand Sizzlers, Some like it hotter or want to spend more than others in their home

• On-off Switchers, Turn it on and off to try and make sure home is only warm when someone is in

• Toasty Cruisers, Love feeling cosy and prefer not to put clothes on if they are cold

Params

n_households initial_occupancy initial_act_occ start_datetime logger

Data

None.

Step input

occupancy active_occupancy

Output

get_thermostat_temperatures()

Step size

10 Minutes.

CREST heating

class demod.simulators.heating_simulators.CrestControls(n_households, is_combi_boiler=None, **kwargs)

NotImplemented yet

Load simulator

This simulator combines all previous simulators in a single simulator. This is very convenient for simple simulations.

class demod.simulators.load_simulators.LoadSimulator(n_households, start_datetime=datetime.datetime(2014, 1, 1, 4, 0), include_heating=True, include_climate=True, initial_outside_temperature=5.0, data=<demod.datasets.Germany.loader.GermanDataHerus object>, **kwargs)

Simulates the full load of households.

This simulator accepts different simulator as inputs.

The simulator can accept an external weather simulator that simulates temperature and irradiation.

It can also accept external heating systems handling the heat production.

The data inputs of this simulator can vary depending wether the heating simulator or the weather simulator is included. Also, the simulator might use a different activity simulator based on the data input. (see the code for more information)

Contains:

• The activity of the residents

• The weather (Temperature and Irradiance)

• Lighting

• Appliances (electric + domestic hot water)

• Heating (building thermal dynamics + heating system)

include_heating

Wether to include the heating of the households

Type

bool

include_climate

Wether to simulate internally the climate (requires external inputs if not.)

Type

bool

Params

n_households heatdemand_algo data initial_outside_temperature include_heating include_climate logger

Data

load_sparse_tpm() load_tpm() load_population_subgroups() load_activity_probability_profiles() load_appliance_ownership_dict() load_appliance_dict() load_crest_lighting() load_bulbs_config() load_heating_system_dict() load_thermostat_dict() load_buildings_dict()

Step input

None

Optional step input

external_outside_temperature external_irradiance external_target_temperature external_heat_outputs external_dhw_outputs external_sh_outputs external_cylinder_temperature

Output

get_room_temperature() get_total_heat_demand() get_dhw_demand() get_sh_demand() get_power_demand() get_controls()

Step size

1 Minute

step(external_outside_temperature=None, external_irradiance=None, external_target_temperature=None, external_heat_outputs=None, external_dhw_outputs=None, external_sh_outputs=None, external_cylinder_temperature=None)

Step function for a load simulator.

Can accepts external inputs for some of the subsimulators.

Parameters

• external_outside_temperature (Optional[float]) –

• external_irradiance (Optional[float]) –

• external_target_temperature (Optional[Union[Dict[str, numpy.ndarray], numpy.ndarray]]) –

• external_heat_outputs (Optional[Union[Dict[str, numpy.ndarray], numpy.ndarray]]) –

• external_dhw_outputs (Optional[numpy.ndarray]) –

• external_sh_outputs (Optional[numpy.ndarray]) –

• external_cylinder_temperature (Optional[numpy.ndarray]) –

Return type

None