modules package 

modules.Agent_properties module 

Defines classes for agent socio-cognitive properties and preferences.

This module contains the building blocks for an agent’s intrinsic profile, often referred to as their “milieu.” These classes encapsulate an agent’s preferences for heating systems and information sources, their personal standards for evaluating options, and the cognitive weights used in their decision-making processes. These properties are typically initialized from external data tables and randomized to create heterogeneity among agents.

Authors:

Ivan Digel <ivan.digel@uni-kassel.de>
Sascha Holzhauer <sascha.holzhauer@uni-kassel.de>

class Milieu(table, milieu_type='Generalized')[source]

Bases: object

A container for an agent’s socio-cognitive profile. This class represents an agent’s “milieu,” which groups together all their intrinsic preferences, standards, and cognitive weights. It is initialised for a specific milieu type (e.g., “Mainstream,” “Leading”) and serves as a central object for an agent’s characteristics.

Parameters:

tableMilieu_table: A data object containing the parameters for all milieu types.
milieu_typestr, optional: The specific type of milieu to initialize, by default “Generalized”.

Attributes:

unique_iduuid.UUID: A unique identifier for the milieu instance.
milieu_typestr: The name of the milieu.
heating_preferencesHeating_preferences: An object holding the agent’s preferences for heating system attributes.
source_preferencesInformation_source_preferences: An object holding the agent’s preferences for information sources.
standardPersonal_standard: An object defining the agent’s thresholds for decision-making.
tpb_weightstuple[float, float, float]: A tuple containing the weights for attitude, social norm, and perceived behavioural control in the Theory of Planned Behaviour.
ra_exposuredict: A dictionary of exposure values for the relative agreement model.
uncertainty_factor: float: USed during risk calculation to define the attitude towards unknown information

Initializes a milieu defining all agent preferences and standards.

Parameters:

tableMilieu_table: A data object containing the parameters for all milieu types.
milieu_typestr, optional: The specific type of milieu to initialize, by default “Generalized”.

generate_TPB_weights(params)[source]

Generate randomised weights for Theory of Planned Behaviour factors.

This method creates a set of weights for the three components of the Theory of Planned Behaviour (TPB): attitude, social norm, and perceived behavioural control. The weights are drawn from a uniform distribution, where the bounds are determined by a mean value specific to the milieu and a standard deviation from the global settings.

Parameters:

paramspandas.Series: A series containing the mean TPB weights for the milieu.

Returns:

dict: A dict containing the generated weights for attitude, social norm, and control, respectively.

class Heating_preferences(table, milieu_type='Generalized')[source]

Bases: object

This class represents an agent’s set of preferences (weights) concerning the different characteristics of a heating system. Each preference is generated as a random value drawn from a Beta distribution to create individual variations based on the agent’s milieu.

Parameters:

tableMilieu_table: The data object containing parameters for all milieus.
milieu_typestr, optional: The specific milieu to generate preferences for, by default “Generalized”.

Initializes preferences for heating system parameters.

Parameters:

tableMilieu_table: The data object containing parameters for all milieus.
milieu_typestr, optional: The specific milieu to generate preferences for, by default “Generalized”.

generate_preferences(alpha, beta)[source]

Generates a single preference value from a Beta distribution.

Parameters:

alphafloat: The alpha shape parameter for the Beta distribution.
betafloat: The beta shape parameter for the Beta distribution.

Returns:

float: A random value between 0 and 1 representing a preference weight.

class Information_source_preferences(table, milieu_type='Generalized')[source]

Bases: object

This class represents an agent’s preferences for various information sources (e.g., internet, plumber, neighbors). The preferences are generated as a set of probabilities that sum to 1, drawn from a Dirichlet distribution. This determines the likelihood that an agent will choose one source over another.

Parameters:

tableMilieu_table: The data object containing parameters for all milieus.
milieu_typestr, optional: The specific milieu to generate preferences for, by default “Generalized”.

Initializes preferences for different information sources.

Parameters:

tableMilieu_table: The data object containing parameters for all milieus.
milieu_typestr, optional: The specific milieu to generate preferences for, by default “Generalized”.

class Personal_standard(table, milieu_type='Generalized')[source]

Bases: object

This class holds the set of thresholds that an agent uses to evaluate whether a heating system is still acceptable. These standards apply to specific attributes. It also includes a lifetime threshold, which determines how close to the end of its lifespan a system must be before the agent considers replacing it.

Parameters:

tableMilieu_table: The data object containing parameters for all milieus.
milieu_typestr, optional: The specific milieu to define standards for, by default “Generalized”.

Initializes the personal standards and decision thresholds.

Parameters:

tableMilieu_table: The data object containing parameters for all milieus.
milieu_typestr, optional: The specific milieu to define standards for, by default “Generalized”.

modules.Excel_input_read module 

Provides classes for loading and accessing model input data from CSV files.

This module contains container classes responsible for reading specific input data files. Although the module name suggests Excel, it is designed to read data from Comma-Separated Values (CSV) files using the pandas library. Each class corresponds to a key data table required by the model, such as milieu parameters or heating system specifications.

Authors:

Ivan Digel <ivan.digel@uni-kassel.de>
Sascha Holzhauer <sascha.holzhauer@uni-kassel.de>

class Milieu_table[source]

Bases: object

A container for milieu parameters loaded from a CSV file.

Attributes:

contentpandas.DataFrame: A DataFrame holding the milieu parameter data, indexed by milieu type.

Initialises the Milieu_table by loading the data.

class Heating_params_table[source]

Bases: object

A container for heating system parameters loaded from a CSV file. This class reads the primary CSV file containing the technical and economic parameters for all available heating systems. It performs minor cleaning, by stripping whitespace from column headers and setting the system name as the index. The data is accessible through the content attribute.

Attributes:

contentpandas.DataFrame: A DataFrame holding the heating system parameter data, indexed by the system’s name.

Initialises the Heating_params_table by loading and preparing the data.

class Heating_params_dynamics_table[source]

Bases: object

A container for the dynamic parameters of heating systems.

This class reads the CSV file that contains time-series or dynamic data related to heating system parameters, such as evolving fuel prices or emissions factors. The data is loaded into a pandas DataFrame and is accessible through the content attribute.

Attributes:

contentpandas.DataFrame: A DataFrame holding the dynamic parameter data for heating systems.

Initializes the Heating_params_dynamics_table by loading the data.

modules.Heating_systems module 

Defines the classes and methods for all heating systems in the simulation.

This module provides the core data structures for representing heating systems. It includes a generic Heating_system base class that defines the common attributes and functionalities shared by all systems.

Specific heating technologies are implemented as subclasses. These subclasses inherit the common framework from the base class but are initialised with their own unique parameters loaded from external data files.

Authors:

Ivan Digel <ivan.digel@uni-kassel.de>
Sascha Holzhauer <sascha.holzhauer@uni-kassel.de>

init_param_table()[source]: Initialises the global heating system parameter table. This function must be called once at the beginning of a simulation run before any Heating_system objects are created. It creates an instance of Heating_params_table, loading the data from the input file and making it globally accessible for all heating system instances.

class Heating_system[source]

Bases: object

A base class representing a generic heating system. This class serves as the blueprint for all heating system types in the model. It defines the core attributes and perceived characteristics. It also contains the methods for calculating key performance and cost indicators, including installation costs, fuel costs, operating costs, and emissions.

Attributes:

unique_iduuid.UUID: A unique identifier for the system instance.
tablepandas.Series: The row from the parameters table corresponding to the system type.
ageint: The number of steps (weeks) since the system was installed.
breakdownbool: A flag indicating if the system has broken down.
investmentfloat or None: The remaining investment cost to be paid back.
ratingfloat or None: An agent’s calculated attitude (rating) towards this system.
paramsdict: A dictionary holding the core parameters of the system. Each key maps to a list of two values: the parameter’s point value and its associated uncertainty (e.g., [value, uncertainty]).
riskinessfloat: A calculated score from 0 to 1 representing the perceived riskiness of installing this system.
weibull_lifetimebool: Defines whether the lifetime will be calculated using Weibull or Uniform

Initializes a new Heating_system instance with default values.

generate_lifetime(min_weeks, max_weeks, shape=None, scale=None)[source]

Generates a random lifetime for the system, using one of two modes.

Mode 1: Uniform (Default): If ‘shape’ and ‘scale’ are NOT provided (or are None), this generates a uniform random integer between ‘min_weeks’ and ‘max_weeks’ (inclusive).
Mode 2: Weibull: If ‘shape’ and ‘scale’ ARE provided, this generates a random lifetime from a Weibull distribution. In this mode, ‘min_weeks’ and ‘max_weeks’ are IGNORED.

The final lifetime is rounded to the nearest integer.

Parameters:

min_weeksint: The minimum possible lifetime (inclusive) for the uniform distribution. Ignored if ‘shape’ and ‘scale’ are provided.
max_weeksint: The maximum possible lifetime (inclusive) for the uniform distribution. Ignored if ‘shape’ and ‘scale’ are provided.
shapefloat, optional: The shape parameter (k) for the Weibull distribution. If provided, ‘scale’ must also be provided.
scalefloat, optional: The scale parameter (lambda) for the Weibull distribution. If provided, ‘shape’ must also be provided.

Returns:

int: The generated lifetime in weeks.

get_name()[source]

Returns the name of the heating system class.

Returns:

str: The class name as a string.

breakdown_check()[source]

Check if the system’s age has exceeded its lifetime.

If the age is greater than the system’s generated lifetime, the breakdown flag is set to True.

payback_check()[source]

Reduce the remaining investment value.

This method is called periodically to simulate the payback of the initial investment.

calculate_all_attributes(area=None, energy_demand=None, house=None, heat_load=None)[source]

Calculates all cost and performance attributes for the system.

This is a convenience method that runs all individual calculation methods to populate the system’s params dictionary based on the properties of a given house.

Parameters:

areafloat, optional: The living area of the house in square meters.
energy_demandfloat, optional: The specific energy demand of the house in kWh per square meter per year.
houseHouse, optional: A House object from which to derive area, energy_demand, and heat_load. If provided, it overrides other parameters.
heat_loadfloat, optional: The heat load of the house in kW.

calculate_installation_costs(area=None, heat_load=None)[source]

Calculates the installation cost for the heating system.

The calculation logic depends on the system type. Some systems are priced based on the house’s area, while others are priced based on the required heat load.

Parameters:

areafloat, optional: The living area of the house in square meters.
heat_loadfloat, optional: The heat load of the house in kW.

Returns:

float: The total installation cost in EUR.

calculate_operating_costs(area, heat_load)[source]

Calculates the annual operating and maintenance costs (OPEX).

Calculates the OPEX as a fraction of the initial installation cost. For systems with a heat delivery contract, the amortised installation cost is included in the annual OPEX.

Parameters:

areafloat: The living area of the house in square meters.
heat_loadfloat: The heat load of the house in kW.

Returns:

float: The total annual operating costs in EUR.

calculate_fuel_costs(energy_demand)[source]

Calculates the annual energy costs.

Parameters:

energy_demandfloat: The total final energy demand of the house in kWh per year.

Returns:

float: The total annual fuel costs in EUR.

calculate_emissions(energy_demand)[source]

Calculate the annual CO2 equivalent emissions.

Parameters:

energy_demandfloat: The total final energy demand of the house in kWh per year.

Returns:

float: The total annual emissions in grams of CO2 equivalent.

calculate_energy_demand(energy_demand, area)[source]

Calculates the final energy demand.

This method adjusts a house’s specific energy demand by applying a system-specific efficiency factor. The factor is chosen from a list based on which predefined energy demand class is closest to the house’s demand.

Parameters:

energy_demandfloat: The specific energy demand of the house in kWh per square meter per year.
areafloat: The living area of the house in square meters.

Returns:

float: The total final energy demand in kWh per year.

calculate_risk(agent)[source]

This method computes a ‘riskiness’ score between 0 and 1. The score is an average of several factors, including the financial risk from a potential loan and the system-specific uncertainty mitigated by the share of neighbours that have adopted the same system.

Parameters:

agentHouseowner: The agent for whom the risk is being calculated.

count_neighbours(agent)[source]

This helper method counts the fraction of an agent’s neighbours who have installed the same type of heating system. It returns a value representing the inverse of this fraction, where 1 indicates maximum uncertainty (no neighbours have the system) and 0 indicates minimum uncertainty (all neighbours have the system).

Parameters:

agentHouseowner: The agent whose neighbours are being checked.

Returns:

float: A value between 0 and 1 representing social uncertainty.

class Heating_system_oil(table=None)[source]

Bases: Heating_system

Represents an oil-fired heating system.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the oil heating system with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_gas(table=None)[source]

Bases: Heating_system

Represents a gas-fired heating system.

This class inherits from Heating_system and sets the specific parameters for a gas heating system by loading them from the global params_table.

Initialises the gas heating system with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_heat_pump(table=None)[source]

Bases: Heating_system

Represents an independent heat pump.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the heat pump heating system with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_electricity(table=None)[source]

Bases: Heating_system

Represents an electricity-based heating system.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the electricity-based heating with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_pellet(table=None)[source]

Bases: Heating_system

Represents a pellet heating system.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the pellet heating system with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_network_district(table=None)[source]

Bases: Heating_system

Represents a district grid-based heating system.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the district heating with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_network_local(table=None)[source]

Bases: Heating_system

Represents a hot local network heating system.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the hot local network heating with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_heat_pump_brine(table=None)[source]

Bases: Heating_system

Represents a heat pump-based cold local network heating system.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the heat pump-based cold local network with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_GP_Joule(table=None)[source]

Bases: Heating_system

Represents a hot local network heating system provided by the firm “GP Joule”.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the hot local network provided by the firm GP Joule with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

class Heating_system_vacuum_tube(table=None)[source]

Bases: Heating_system

Represents a vacuum tube heating system. Not actually a heating system and is not used anywhere in the model.

This class inherits from Heating_system and sets the specific parameters for an oil heating system by loading them from the global params_table.

Initialises the vacuum tube heating system with its specific parameters.

Parameters:

tableHeating_params_table, optional: The parameter table to use. If None, the global params_table is used, by default None.

modules.Information_sources module 

This module provides the classes and logic for how agents gather information. It features a base Information_source class that implements the core information-seeking process, where an agent receives potentially biased and uncertain data about a heating system.

Specific subclasses, such as Information_source_internet and Information_source_plumber, represent different channels through which an agent can seek information. Each source has its own characteristics, including the scope of its knowledge (content), the cost to consult it, and the specific interaction mechanics.

Authors:

Ivan Digel <ivan.digel@uni-kassel.de>
Sascha Holzhauer <sascha.holzhauer@uni-kassel.de>
Dmytro Mykhailiuk <dmytromykhailiuk6@gmail.com>

class Information_source[source]

Bases: object

A base class for a generic source of information.

This class provides the structure and methods for all information sources in the model. It defines standard attributes like search cost and distortion levels and contains the core data_search method, which simulates the process of an agent acquiring and perceiving information.

Attributes:

costint: The cognitive resource cost for an agent to perform one search action.
distortionfloat: The base (maximum) factor for distorting a heating system’s true parameters.
min_distortionfloat: The minimum distortion (for a 100% market share system).
uncertainty_lowerfloat: The lower bound for the uncertainty range applied to parameters.
uncertainty_upperfloat: The upper bound for the uncertainty range applied to parameters.
contentlist or None: A list of heating system names that this source can provide information on.

Initialises a generic Information_source instance.

This constructor sets the default attributes for an information source, such as cost and distortion levels, by loading them from the global settings.

classmethod instantiate_subclasses()[source]

Creates and returns an instance of each direct subclass.

This factory method is a convenient way to get a list of all available information source objects in the simulation.

Returns:

list[Information_source]: A list containing one instance of each subclass.

data_search(agent, cost)[source]

Simulates an agent’s process of searching for information using Internet or Magazine.

This method models an agent spending cognitive resources to acquire information about a heating system. The process involves several steps: 1. A random heating system is selected from the source’s content. 2. A “perceived” version of this system is created, where its true

parameters are distorted.

The distortion is “pessimistic-only” (>= 1.0) and its upper bound is based on the system’s market share. - New tech (low share) = wide range [0.0, MAX] -> unpredictable - Old tech (high share) = narrow range [0.0, MIN] -> predictable
An uncertainty range is added to each perceived parameter.
If the system is new to the agent, it’s added to their knowledge base.
If the agent already knows the system, their existing perception is updated using a relative agreement mechanism.

The source also add knowledge about subsidies. The search continues until the agent runs out of cognitive resources, finds a satisfactory option, or becomes overloaded with information.

Parameters:

agentHouseowner: The agent performing the information search.
costint: The cognitive resource cost for this specific search action.

class Information_source_internet[source]

Bases: Information_source

Represents the Internet as a source of information.

Initialises the Internet source. The Internet is configured to have knowledge of all heating systems and subsidies listed in the project settings.

organize_subsidies()[source]

Populate the source’s knowledge of available subsidies.

This method compiles a list of subsidies applicable to the heating systems that the source provides information about.

class Information_source_magazine[source]

Bases: Information_source

Represents a professional magazine as a source of information.

Initialises the magazine source.

A magazine is configured with a limited set of conventional heating systems that it can provide information about.

organize_subsidies()[source]: Populates the source’s knowledge of available subsidies. This method compiles a list of subsidies applicable to the heating systems that the source provides information about.

class Information_source_plumber[source]

Bases: Information_source

Represents a plumber as a source of information. Not the plumber itself. This subclass facilitates exclusively the data search part of houseowner-plumber interaction.

Initializes the plumber information source.

data_search(agent, cost)[source]

Simulate an agent consulting a plumber.

This method models the specific interaction of ordering a consultation from a plumber. The agent finds a plumber (if they don’t already have one) and requests a service. The actual information exchange is then handled by the plumber agent’s logic.

Parameters:

agentHouseowner: The agent seeking a consultation.
costint: The cognitive resource cost of contacting the plumber.

class Information_source_neighbours[source]

Bases: Information_source

Represents neighbours as a source of information. Not the neighbours themselves. This subclass facilitates exclusively the information search among neighbours.

Initialises the neighbours information source.

data_search(agent, cost)[source]

Simulate an agent asking their neighbours for information.

This method triggers the agent’s behaviour to interact with their neighbours to gather opinions and information about their heating systems. The information exchange is handled by the agent’s ask_neighbours method.

Parameters:

agentHouseowner: The agent asking neighbors.
costint: The cognitive resource cost (not used in this implementation).

class Information_source_energy_advisor[source]

Bases: Information_source

Represents an energy advisor as a source of information. Not the EA itself. This subclass facilitates exclusively the data search part of houseowner-EA interaction.

Initialises the energy advisor information source.

data_search(agent, cost)[source]

Simulates an agent consulting an energy advisor. This method models the agent finding and ordering a consultation from an energy advisor. The detailed information exchange is subsequently handled by the energy advisor agent’s logic.

Parameters:

agentHouseowner: The agent seeking a consultation.
costint: The cognitive resource cost of contacting the advisor.

generate_imperfect_system(agent, system_name)[source]

Create a perceived, imperfect representation of a heating system.

This function simulates an agent’s imperfect perception of a heating system. It takes a system name, creates an instance with its “true” attributes calculated for the agent’s house, and then applies a random “pessimistic-only” distortion and an uncertainty range to its parameters.

The distortion’s upper bound is based on the system’s market share.

Parameters:

agentHouseowner: The agent for whom the system perception is being generated.
system_namestr: The name of the heating system class to generate.

Returns:

Heating_system: The newly created Heating_system object with distorted and uncertain parameters.

modules.Rng module 

Manages random number generation to ensure model reproducibility.

This module provides a suite of functions that serve as access points to separate, seeded random number generators (RNGs). By using distinct RNG streams for different model components (e.g., model setup, agent behaviour), it prevents a change in one stochastic process from affecting the outcomes of others.

Each function initialises a singleton NumPy Generator instance on its first call, using a specific seed from the project’s configuration file. All subsequent calls return the same instance. This ensures that the sequence of random numbers for each stream is consistent across identical simulation runs. The module also includes an optional debugging utility to log the call stack each time an RNG is accessed.

Authors:

Ivan Digel <ivan.digel@uni-kassel.de>
Sascha Holzhauer <sascha.holzhauer@uni-kassel.de>

init()[source]

Initialise the output directory for RNG invocation logs.

This is an internal helper function called by print_stacktrace on its first invocation to ensure the target directory for logging exists.

rng_model_init(message: str = '')[source]

Provides the RNG instance for model initialisation.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for model initialisation.

rng_model_run(message: str = '')[source]

Provides the RNG instance for the main model run loop.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for the model’s run phase.

rng_house_init(message: str = '')[source]

Provides the RNG instance for the initialisation of instances of the House class.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for model initialisation.

rng_houseowner_run(message: str = '')[source]

Provides the RNG instance for the Houseowner behaviour-related random processes.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for model initialisation.

rng_plumber_run(message: str = '')[source]

Provides the RNG instance for the Plumber behaviour-related random processes.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for model initialisation.

rng_milieu_init(message: str = '')[source]

Provides the RNG instance for the initialisation of the Houseowner milieu.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for model initialisation.

rng_heating_init(message: str = '')[source]

Provides the RNG instance for the initialisation of the Heating_system related initialisation.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for model initialisation.

rng_information_source_run(message: str = '')[source]

Provides the RNG instance for the interaction between Houseowners and information sources.

Parameters:

messagestr, optional: A message to include in the stack trace log for debugging context, by default “”.

Returns:

numpy.random.Generator: The singleton RNG instance for model initialisation.

print_stacktrace(name='', message: str = '')[source]

Log the current call stack to a file for debugging. When enabled via settings.output.randomstreaminvocations, this function is called by an RNG provider to record the sequence of function calls that led to the request for a random number. It helps trace the exact source of randomness and verify that the correct RNG streams are being used.

Parameters:

namestr, optional: The prefix for the log file’s name, by default “”.
messagestr, optional: A contextual message to include in the log entry, by default “”.

modules.Scenario module 

Defines the experimental scenarios for the simulation.

This module contains the classes that control the specific conditions and interventions for different simulation experiments. It features a base Scenario class that provides the core structure and default behaviours.

Various subclasses inherit from this base class to implement specific future pathways or policy interventions. Each scenario can modify the model’s initial state (via the setup method) and introduce dynamic events during the simulation (via the impact method).

Authors:

Ivan Digel <ivan.digel@uni-kassel.de>
Sascha Holzhauer <sascha.holzhauer@uni-kassel.de>

class Scenario[source]

Bases: object

A base class for defining an experimental scenario.

This class provides the fundamental structure (setup and impact methods) and default behaviours that can be inherited and extended by specific scenario subclasses. It also contains the logic for common, optional interventions like plumber training or information campaigns, which can be activated via the global settings.

Attributes:

idstr: The unique identifier for the scenario.
hs_targetsdict: A dictionary defining the target market shares for heating systems in this scenario.
visited_agentslist: A list to keep track of agents who have been targeted by an intervention.

Initializes the scenario’s state-tracking attributes.

id = '00'

setup(model)[source]

Applies initial, one-time modifications to the model.

This method is called once at the beginning of a simulation (step 0) to set up the specific conditions of the scenario. The default behaviour gives agents who already own a heat pump a head start in knowledge about various systems and subsidies. Subclasses can extend this to implement their unique starting conditions.

Parameters:

modelModel: The main model instance.

impact(model)[source]

Applies dynamic interventions or events during the simulation.

This method is called at each step of the simulation to introduce changes or trigger events. It serves as the entry point for various policy interventions that can be enabled in the settings, such as plumber training programs, information campaigns, technology bans, or replacement mandates.

Parameters:

modelModel: The main model instance.

class Scenario_none[source]

Bases: Scenario

A default scenario with no specific modifications.

This scenario serves as a baseline or control, applying only the default setup and impact logic from the base Scenario class.

Initializes the scenario’s state-tracking attributes.

id = '01'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_perfect[source]

Bases: Scenario

A scenario with perfect information and no feasibility constraints.

In this idealised scenario, all agents start with complete and perfect knowledge of all available heating systems. Information is not distorted, and all systems are considered feasible options from the beginning.

Initializes the scenario’s state-tracking attributes.

id = '02'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_network_district[source]

Bases: Scenario

A scenario where district heating is the sole targeted technology.

This scenario models a future where policy and infrastructure are focused exclusively on district heating. Competing network-based technologies are made infeasible for all agents from the start of the simulation.

Initializes the scenario’s state-tracking attributes.

id = '03'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_network_local_hot[source]

Bases: Scenario

A scenario where local ‘hot’ network heating is the sole targeted technology.

This scenario models a future focused exclusively on local ‘hot’ heating networks. It makes district networks and other system-based options (brine heat pumps, GP Joule) infeasible for all agents from the start of the simulation.

Initializes the scenario’s state-tracking attributes.

id = '04'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_network_local_cold[source]

Bases: Scenario

A scenario where brine heat pumps (cold network) are the sole targeted technology.

This scenario models a future pathway centered on local “cold” networks that rely on brine heat pumps. Competing centralised network options are made infeasible for all agents.

Initializes the scenario’s state-tracking attributes.

id = '05'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_heat_pumps[source]

Bases: Scenario

A scenario where air-source heat pumps are the sole targeted technology.

This scenario simulates a strong policy push towards electrification of heating via individual air-source heat pumps. All network-based heating options are made infeasible.

Initializes the scenario’s state-tracking attributes.

id = '06'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_mix_pellet_heat_pump[source]

Bases: Scenario

A scenario targeting a mix of heat pumps and pellet systems.

This scenario explores a future with two desired renewable, decentralised heating options. It assumes no large-scale heating networks are built, making those options infeasible for all agents. The target market share is 80% heat pumps and 20% pellet systems.

Initializes the scenario’s state-tracking attributes.

id = '07'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_mix_pellet_heat_pump_network[source]

Bases: Scenario

A scenario targeting a mix of a local hot network, heat pumps, and pellet systems.

This complex scenario models a spatially differentiated energy transition. A local ‘hot’ heating network is available, but only for agents outside the ‘Sued’ subarea. All agents can choose between heat pumps and pellet systems. Other network types are globally infeasible.

Initializes the scenario’s state-tracking attributes.

id = '08'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_pellets[source]

Bases: Scenario

A scenario where pellet heating systems are the sole targeted technology.

This scenario models a future pathway focused on biomass as the primary renewable heating source. All network-based heating options and heat pumps that require significant grid infrastructure are made infeasible.

Initializes the scenario’s state-tracking attributes.

id = '09'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_mix_heat_pump_network_cold[source]

Bases: Scenario

A scenario targeting a mix of air-source and local cold network based on brine-source heat pumps.

This scenario simulates a future focused entirely on different types of heat pump technology, representing a full electrification pathway. All other centralised heating network options are made infeasible.

Initializes the scenario’s state-tracking attributes.

id = '10'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

class Scenario_mix_GP_Joule[source]

Bases: Scenario

A scenario targeting a mix of a local hot network, heat pumps, and pellet systems. The default hot network is replaced with the option provided by the firm GP Joule.

It assumes no other large-scale heating networks are built, making those options infeasible for all agents.

Initializes the scenario’s state-tracking attributes.

id = '11'

setup(model)[source]: Scenario specific model adjustments

impact(model)[source]: Scenario specific impacts during model runs

apply_subsidies(agent, system)[source]

Applies all known and applicable subsidies to a given heating system.

Parameters:

agentHouseowner: The agent considering the system.
systemHeating_system: The heating system to which subsidies will be applied.

organize_subsidies(agent)[source]

Populates an agent’s knowledge base with available subsidies.

This function simulates an agent learning about the various subsidies available for the heating systems they know. It populates the agent’s known_subsidies_by_hs dictionary.

Parameters:

agentHouseowner: The agent who is learning about subsidies.

plumber_training_program(model, system_name: str)[source]

Simulates a training program for plumbers. This function identifies all plumber agents in the model who do not yet have knowledge of a specific heating system and makes them “trained” in it, adding it to their knowledge base.

Parameters:

modelModel: The main model instance.
system_namestr: The name of the heating system for the training program.

information_campaign(model, system_names: list, mode: str, scenario)[source]

Simulates a large-scale information campaign intervention.

This function models different types of information campaigns designed to influence houseowners. The behaviour depends on the specified mode: - ‘Direct_informing’: A set number of agents receive direct information. - ‘Energy_advisor’: A set number of agents are prompted to consult an energy advisor. - ‘Risk_targeting’: A campaign designed to mitigate the perceived risk of certain technologies.

Parameters:

modelModel: The main model instance.
system_nameslist: A list of heating systems to be promoted in the campaign.
modestr: The type of campaign to run (‘Direct_informing’, ‘Energy_advisor’, or ‘Risk_targeting’).
scenarioScenario: The currently active scenario instance, used to track visited agents.

enforce_heating_systems(model, systems_names: list)[source]

Enforces a limited set of allowed heating systems.

This function models a regulatory policy where only a specific list of heating systems are allowed for new installations. All other systems are made infeasible for all agents.

Parameters:

modelModel: The main model instance.
systems_nameslist: A list of the only heating system names that are allowed.

issue_replacement_mandates(model)[source]

Simulates the policy of mandating the replacement of inefficient systems.

This function models two types of mandates: 1. Performance-based: A fraction of systems exceeding a certain emissions

threshold are forced into a ‘breakdown’ state each year.

Technology-based: Any systems of a specific type (e.g., oil boilers) are forced into a ‘breakdown’ state.

Parameters:

modelModel: The main model instance.

open_house_measure(model, system_names=['Heating_system_heat_pump'], milieus=['Leading'], freq=0)[source]

Asks Heat pump users to share their satisfaction and knowledge with their neighbours Based on ‘Woche der Wärmepumpe’ launched by BMWK and dena.

Parameters:

modelModel: The main model instance.
system_nameslist: A list of heating systems to be promoted in the campaign.
milieus: list: A list of milieus that would actively participate as promoters

modules.Triggers module 

Defines the trigger events that initiate an agent’s decision-making process.

This module contains the classes that represent various events or conditions, known as “triggers,” which can prompt a Houseowner agent to reconsider their current heating system. It includes a generic Trigger base class and numerous subclasses, each modelling a specific event such as a system breakdown, a fuel price shock, or social influence from a neighbour.

When a trigger becomes active for an agent, its impact method is executed, typically moving the agent from a passive state into the first stage of the decision-making model.

Authors:

Ivan Digel <ivan.digel@uni-kassel.de>
Dmytro Mykhailiuk <dmytromykhailiuk6@gmail.com>

class Trigger[source]

Bases: object

A base class for an event that can trigger an agent’s decision process.

This class provides the structure for all triggers. Its primary role is to define the impact method, which is called when the trigger affects an agent. The base impact method handles data collection and ensures an agent is not re-triggered if they are already in an active decision process.

Initialises a new Trigger instance.

impact(agent)[source]

Applies the trigger’s effect to an agent.

This base method logs the trigger’s activation for data collection and contains a guard clause to prevent the trigger from affecting an agent who is already in an active decision-making stage.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_none[source]

Bases: Trigger

A null trigger that has no effect.

Initialises a new Trigger_none instance.

impact(agent)[source]: Applies only the impact from the superclass.

class Trigger_price_shock(factor: float = 1)[source]

Bases: Trigger

A trigger representing a sudden, significant increase in fuel price.

Initialises the price shock trigger.

Parameters:

factorfloat, optional: The multiplication factor to apply to the agent’s current fuel cost, by default 1.

impact(agent)[source]

Increases the agent’s perceived fuel cost and starts the decision process.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_lifetime[source]

Bases: Trigger

A trigger representing the agent’s awareness that their system is nearing its end of life.

Initializes a new Trigger_lifetime instance.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_neighbour_jealousy[source]

Bases: Trigger

A trigger representing social influence from a neighbor’s new heating system.

Initializes a new Trigger_neighbour_jealousy instance.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_adoptive_comparsion[source]

Bases: Trigger

A trigger representing an invitation from a neighbour to adopt a heating system of the same type.

This trigger occurs when a neighbour installs a new heating system and proposes to install one of the same type to the agent.

Initialises the adoptive comparison trigger.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

This trigger simulates the effect of being prompted to think about one’s own heating system after a neighbour asks for advice.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_asked_by_neighbour[source]

Bases: Trigger

A trigger representing being asked for an opinion by a neighbour.

Initialises a new Trigger_asked_by_neighbour instance.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

This trigger simulates the effect of being prompted to think about one’s own heating system after a neighbour asks for advice.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_breakdown[source]

Bases: Trigger

A trigger representing a critical failure of the agent’s heating system.

Initializes a new Trigger_breakdown instance.

impact(agent)[source]

Forces the agent directly into the second stage of the decision process.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_information_campaign(system_names)[source]

Bases: Trigger

A trigger representing an agent being targeted by an information campaign.

Initializes the information campaign trigger.

Parameters:

system_nameslist[str]: A list of heating system names being promoted by the campaign.

impact(agent)[source]

Introduces idealised versions of promoted systems to the agent’s knowledge.

This trigger adds perfected versions of the promoted heating systems to the agent’s set of known alternatives, then moves the agent into the first stage of the decision process.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_consulted[source]

Bases: Trigger

A trigger representing an agent being nudged to thinking about the replacement by a consultation.

Initialises a new Trigger_consulted instance.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

This trigger is typically activated by an external intervention, like an information campaign that encourages houseowners to think about the replacement.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_risk_targeting_campaign[source]

Bases: Trigger

A trigger from a campaign designed to mitigate perceived technology risk.

Initializes the risk-targeting campaign trigger.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_availability[source]

Bases: Trigger

A trigger representing a change in the availability of a heating system.

Initialises a new Trigger_availability instance.

impact(agent)[source]

Forces the agent directly into the second stage of the decision process.

This trigger models an external event where an agent finds out that their current heating type will be no longer available for the installation in some (near) future, forcing them to think about installing a new one of the same type to avoid the “forced” switch to another heating technology.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_fuel_price[source]

Bases: Trigger

A trigger representing general awareness of changing fuel prices.

Initialises a new Trigger_fuel_price instance.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

This trigger models a non-shock-based response to fuel price volatility, prompting the agent to begin considering their heating options.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.

class Trigger_owner_change[source]

Bases: Trigger

A trigger representing general awareness of changing fuel prices.

Initialises a new Trigger_fuel_price instance.

impact(agent)[source]

Moves the agent into the first stage of the decision process.

This trigger models a non-shock-based response to fuel price volatility, prompting the agent to begin considering their heating options.

Parameters:

agentHouseowner: The agent to be impacted by the trigger.