agents package

Subpackages

agents.EnergyAdvisor module

This module provides the implementation for the EnergyAdvisor, an intermediary agent that consults Houseowners on heating systems, subsidies, and financing. It includes the EnergyAdvisor class itself and the ConsultationServiceEnergyAdvisor class, which handles the logic of performing a consultation.

Authors:
class ConsultationServiceEnergyAdvisor(intermediary=None)[source]

Bases: ConsultationService

A specialized consultation service provided by an EnergyAdvisor.

This service handles the process of a consultation job. When a job is completed, it evaluates heating systems based on the houseowner’s specific situation, applies relevant subsidies, filters for feasibility and affordability, and provides a tailored recommendation.

Initializes the consultation service for an EnergyAdvisor. Sets the job length specific to energy advisors.

Parameters:
intermediaryEnergyAdvisor, optional

The EnergyAdvisor agent providing this service. Defaults to None.

begin_job()[source]

Begins a consultation job by adding it to active jobs and removes it from the job queue.

complete_job(job)[source]

Completes a consultation job and provides advice to the houseowner.

This method performs the core logic of the consultation. It assesses heating systems known to the advisor, calculates house-specific costs, applies subsidies, and filters the options based on the customer’s budget. The most suitable options are then presented to the houseowner.

Parameters:
jobJob

The consultation job to be completed.

class EnergyAdvisor(unique_id: int, model: Model, heating_preferences=None, known_hs=None, known_subsidies=None)[source]

Bases: Intermediary

An intermediary agent providing expert advice on heating systems.

The EnergyAdvisor specializes in knowledge about heating technologies and financial subsidies. It consults houseowners to help them find the most suitable and cost-effective heating solutions based on their specific needs and financial situation.

Attributes:
known_hslist

A list of Heating_system objects the advisor is knowledgeable about.

heating_preferencesHeating_preferences

The preferences used by the advisor to evaluate heating systems.

known_subsidieslist

A list of Subsidy objects the advisor is aware of.

infeasiblelist

A list of heating system names considered infeasible by this advisor.

perceived_uncertaintydict

A mapping of heating system names to perceived uncertainty values.

known_subsidies_by_hsdict

A dictionary organizing known subsidies by the heating systems they apply to.

Serviceslist

A list of services offered by the advisor.

Initializes an EnergyAdvisor agent.

Parameters:
unique_idint

The unique identifier for the agent.

modelModel

The main MESA model instance.

heating_preferencesHeating_preferences, optional

The agent’s preferences for evaluating heating systems.

known_hslist, optional

A list of known heating systems.

known_subsidieslist, optional

A list of known subsidies.

evaluate_system(system)[source]

Evaluates a heating system based on the advisor’s preferences.

This method extends the base evaluate_system from the Intermediary class. It can be modified to include advisor-specific evaluation criteria.

Parameters:
systemHeating_system

The heating system to be evaluated.

Returns:
float

The calculated rating for the system.

share_knowledge(agent)[source]

Shares detailed, house-specific knowledge about heating systems.

The advisor calculates house-specific parameters for its known systems and updates the houseowner’s knowledge base. New systems are added, and existing ones are updated with the advisor’s expert data.

Parameters:
agentHouseowner

The houseowner agent to share knowledge with.

share_rating(agent, systems_list)[source]

Shares the advisor’s ratings of heating systems with a houseowner.

This method updates the houseowner’s neighbours_opinions for each system, effectively influencing the houseowner’s perception of those systems.

Parameters:
agentHouseowner

The houseowner to share ratings with.

systems_listlist

The list of Heating_system objects whose ratings are to be shared.

get_milieu()[source]

Returns the agent’s type for the data collector.

get_opex()[source]

Returns None, as advisors do not have operational expenses.

get_house_area()[source]

Returns None, as advisors are not associated with a house.

agents.House module

agents.Houseowner module

agents.Plumber module

Defines the Plumber agent and its consultation and installation services.

This module contains the Plumber class, an intermediary agent responsible for consulting houseowners about heating system options and installing new systems. It includes two service classes, ConsultationServicePlumber and InstallationServicePlumber, which manage the respective job queues and the logic for these tasks.

Authors:
class ConsultationServicePlumber(intermediary=None)[source]

Bases: Service

A service for handling heating system consultations by a Plumber.

When a consultation job is completed, this service triggers the Plumber’s consultation method, where the Plumber shares knowledge, provides recommendations, or performs a feasibility check on a desired heating system.

Initializes the consultation service for a Plumber. Sets plumber-specific default job duration.

begin_job()[source]

Begins a consultation job.

complete_job(job)[source]

Completes a consultation job by calling the Plumber’s consultation method.

Parameters:
jobJob

The consultation job to be completed.

class InstallationServicePlumber(intermediary=None)[source]

Bases: Service

A service for managing and executing heating system installations.

This service manages the queue for installation jobs. It has a custom queue_job method to handle variable installation times. When a job is completed, it triggers the Plumber’s installation method to finalise the process in the simulation.

Initializes the installation service for a Plumber.

queue_job(houseowner, installation_time)[source]

Adds an installation job to the queue with a specific duration.

Parameters:
houseownerHouseowner

The customer for whom the installation will be performed.

installation_timeint

The specific time required for this type of heating system installation.

begin_job()[source]

Begins an installation job.

complete_job(job)[source]

Completes an installation job by calling the Plumber’s installation method.

Parameters:
jobJob

The installation job to be completed.

class Plumber(unique_id, model, heating_preferences, standard, current_heating, cognitive_resource, aspiration_value, known_hs, suitable_hs, desired_hs, hs_budget, current_breakpoint, current_stage, satisfaction, active_trigger, active_jobs: dict = None, completed_jobs: dict = None, max_concurrent_jobs: int = 1, active_jobs_counter: int = 0, known_subsidies=None)[source]

Bases: Intermediary

An intermediary agent who consults on and installs heating systems.

The Plumber agent models a trade professional who interacts directly with Houseowners. Plumbers have their own knowledge base of heating systems, which can be expanded through training. They provide consultations to help Houseowners choose a system and are responsible for the entire installation process, from feasibility checks to final implementation.

Initializes a Plumber agent.

Parameters:
unique_idint

The unique identifier for the agent.

modelmesa.Model

The main model instance.

heating_preferencesHeating_preferences

The agent’s preferences for evaluating heating systems.

known_hslist

A list of known Heating_system objects.

known_subsidieslist

A list of known Subsidy objects.

Notes

Many parameters are inherited from the Houseowner class for data collector compatibility and may not be directly used in the Plumber’s logic.

suboptimality

Plumber specific parameters below

check_job_completion(steps)[source]

Checks for and finalises any jobs scheduled for completion at the current step.

Parameters:
stepsint

The current simulation step.

estimate_queue_time(q_type)[source]

Estimates the total waiting time for a given service queue.

Parameters:
q_typestr

The name of the service queue (‘Consultation’ or ‘Installation’).

Returns:
int

The estimated total duration in steps for all jobs in the queue.

training(system=None)[source]

Expands the Plumber’s knowledge by learning about a new heating system.

consultation(job)[source]

Performs a consultation for a houseowner.

This method has two main paths: 1. If the houseowner has no desired system, the Plumber shares knowledge

about various systems and provides a recommendation.

  1. If the houseowner has a desired system, the Plumber checks its feasibility, verifies the houseowner’s ability to afford it (including subsidies and loans), updates the final costs, and, if successful, queues an installation job.

Parameters:
jobJob

The consultation job containing the customer information.

recommend(agent)[source]

Recommends the best-rated heating system to a houseowner.

The recommendation is based on the Plumber’s own evaluation of the systems they know.

Parameters:
agentHouseowner

The houseowner to whom the recommendation is given.

installation(job)[source]

Performs the installation of a new heating system for a client.

This method is called when an installation job is completed. It finalises the installation, updates the model’s state (e.g., counters), and deducts the cost from the houseowner’s budget.

Parameters:
jobJob

The installation job containing the customer information.

generate_system(variant)[source]

Creates an instance of a heating system from its class name.

Parameters:
variantstr

The class name of the heating system to create.

Returns:
Heating_system

An instance of the specified heating system.

install_system(agent, heating)[source]

Replaces the agent’s old heating system with a new one.

This is the core logic for the installation, where the houseowner’s current_heating is updated, along with all relevant financial and environmental metrics in the model.

Parameters:
agentHouseowner

The houseowner receiving the new system.

heatingstr

The class name of the heating system to install.

evaluate_system(system)[source]

Rates a heating system based on the Plumber’s own preferences.

Parameters:
systemHeating_system

The heating system to evaluate.

share_systems(agent)[source]

Shares knowledge of other clients’ systems with a houseowner.

Parameters:
agentHouseowner

The agent to share information with.

share_rating(agent)[source]

Shares the Plumber’s ratings of known systems with a houseowner.

Parameters:
agentHouseowner

The agent to share ratings with.

share_knowledge(agent)[source]

Shares attribute knowledge about systems with a houseowner.

Parameters:
agentHouseowner

The agent to share knowledge with.

modify_agent_income(agent, old_system, new_system)[source]

Adjusts a houseowner’s weekly net income after a new system is installed.

The income is modified based on the difference in weekly running costs (fuel and opex) between the old and new heating systems.

Parameters:
agentHouseowner

The agent whose income is being modified.

old_systemHeating_system

The previously installed heating system.

new_systemHeating_system

The newly installed heating system.

check_affordability(agent)[source]

Verifies if a houseowner can afford a new heating system.

Checks both the upfront installation cost against the agent’s budget (including loans) and the ongoing running costs against the agent’s income.

Parameters:
agentHouseowner

The agent whose affordability is being checked.

Returns:
bool

True if the agent can afford the system, False otherwise.

organize_subsidies()[source]

Structures known subsidies into a dictionary for easy lookup. Sorts subsidies by the type of heating system they are applied to.

apply_subsidies(hs, agent)[source]

Applies relevant subsidies to a heating system for a given agent.

Parameters:
hsHeating_system

The heating system to which subsidies will be applied.

agentHouseowner

The agent for whom the subsidy conditions are checked.

get_heating()[source]
get_trigger()[source]
get_stage_dynamics()[source]
get_class()[source]
get_system_age()[source]
get_satisfied_ratio()[source]
get_milieu()[source]
get_opex()[source]
get_preferences()[source]
get_heating_system_evaluation()[source]
get_attributes()[source]
get_comprehensive_metrics()[source]
get_house_area()[source]

Module contents