Illuminator Agent Models

class illuminator.models.Agents.generators.generation_company_agent_v3.GenerationCompanyAgent(**kwargs)

Generation Company Agent that participates in electricity markets by submitting bids.

This agent represents a power generation company that owns a portfolio of power plants and can submit either automated marginal cost-based bids or manual bids to the market.

Parameters:

  • company_name (str) – Name identifier for the generation company

  • automated_bids (bool) – Flag to determine if bids are generated automatically based on marginal costs

  • bids_manual (pd.DataFrame, optional) – Manual bid data if automated_bids is False

Inputs:

portfolio (dict) – Portfolio of power plants with their characteristics (capacity, cost, availability)

Outputs:

None

States:

  • bids (dict) – Current market bids for each power plant

  • profit (float) – Cumulative profit from market operations

bid() → dict

Creates bids for each power plant in the portfolio.

Parameters:

None

Returns:

Dictionary containing bids DataFrame with columns: - Company : str Name of the generation company - Technology : str Type of power plant - Capacity (MW) : float Nominal capacity - Cost (€/MWh) : float Marginal cost - Availability : float Plant availability factor - Available Capacity (MW) : float Actual available capacity - Bid Capacity (MW) : float Capacity offered to market - Bid Price (€/MWh) : float Price offered to market

Return type:

dict

inputs: Dict = {'portfolio': {}}
outputs: Dict = {}
parameters: Dict = {'automated_bids': True, 'bids_manual': None, 'company_name': 'no name'}
states: Dict = {'bids': {}, 'profit': 0}
step(time: int, inputs: dict = None, max_advance: int = 1) → None

Performs a single simulation time step by processing portfolio information and generating market bids. :param time: Current simulation time in hours :type time: int :param inputs: Dictionary containing market inputs and portfolio information :type inputs: dict :param max_advance: Maximum time step advancement in hours, defaults to 1 :type max_advance: int, optional

Returns:

Next simulation time in hours. Returns current time plus model time step size

Return type:

int

time = None
time_step_size: int = 1
class illuminator.models.Agents.justice_agent.justice_agent_v3.JusticeAgent(**kwargs)

Justice evaluator agent that calculates justice metrics for electricity market participants.

This agent monitors market outcomes and calculates justice scores based on company market shares and predefined social parameters. It tracks beta scores (market shares) over time and computes an overall justice score at specified intervals.

Parameters:

  • social_parameters (dict) – Dictionary containing social parameter weights (a,b,c,d) for each company

  • justice_step (int) – Time step at which to calculate final justice scores

  • results_dir (str, optional) – Directory to save justice metric results, defaults to ‘justice_agent_results’

Inputs:

  • market_results (pd.DataFrame) – Market clearing results with company capacities, revenues, costs and profits

  • demand (float) – Total market demand

  • market_clearing_price (float) – Market clearing price

Outputs:

None

States:

  • beta_scores (dict) – Cumulative market shares for each company

  • justice_score (float) – Overall justice metric

  • alpha_scores (dict) – Social parameter weights for each company

calculate_justice_score()

Calculates the justice score based on alpha factors and beta scores. The justice score is computed as the sum of products between alpha factors and beta scores for each company. :returns: The calculated justice score, representing the weighted sum of beta scores :rtype: float

determine_share()

Calculates market share distribution based on supplied capacity of companies. The function calculates beta scores for each company based on their supplied capacity relative to total demand. If the sum of beta scores is less than 1, the remaining share is added to the company with the lowest beta score. The calculated beta scores are then added to the cumulative beta scores. :param None:

Return type:

None

Notes

Updates self.beta_scores dictionary with new cumulative beta scores for each company. Uses self.market_results DataFrame containing ‘Company’ and ‘Supplied Capacity (MW)’ columns. Uses self.demand for total market demand.

inputs: Dict = {'demand': 0, 'market_results': None, 'marketclearingprice': 0}
parameters: Dict = {'justice_step': None, 'results_dir': 'justice_agent_results', 'social_parameters': None}
states: Dict = {'alpha_scores': {}, 'beta_scores': {}, 'justice_score': None}
step(time: int, inputs: dict = None, max_advance: int = 1) → None

Performs a single simulation time step by processing market results and calculating justice metrics. :param time: Current simulation time :type time: int :param inputs: Dictionary containing input values including ‘market_results’, ‘demand’, and ‘market_clearing_price’ :type inputs: dict :param max_advance: Maximum time step advancement, defaults to 1 :type max_advance: int, optional

Returns:

Next simulation time step

Return type:

int

Notes

The method processes market results, determines company shares, and calculates justice scores at specified intervals. Results are saved to CSV files and state variables are updated. Market results include company data with supplied capacity, revenue, costs and profits.

class illuminator.models.Agents.operators.operator_v3.Operator_Market(**kwargs)

Market operator agent responsible for clearing the electricity market.

This agent processes bids from generators, calculates market clearing prices using merit order principles, and determines accepted capacities and financial results for market participants.

Parameters:

results_dir (str) – Directory to save market results and visualizations

Inputs:

bids (dict or list[dict]) – Bid information from generators containing prices and capacities

Outputs:

None

States:

  • market_clearing_price (float) – Cleared market price in €/MWh

  • market_results_summary (dict) – Summary of market results including revenues and profits

  • demand (float) – Total market demand in MW

calculate_balance(bids)

Calculates market clearing price and generates results based on submitted bids.

The function processes all bids to determine the market clearing price based on the merit order, calculates accepted capacities, and computes financial results for each company including revenue, costs, and profits. It also triggers the creation of a merit order curve visualization.

Parameters:

bids (list) – List of DataFrames containing bid information from each company

Returns:

Dictionary containing: - market_clearing_price: float representing the cleared market price - results: DataFrame with company-wise financial and operational results

Return type:

dict

create_merit_order_curve(all_bids_sorted, demand, market_clearing_price)

Creates a merit order curve plot based on sorted bids and market clearing results.

The function visualizes the merit order by plotting each bid as a bar segment, showing the cumulative generation capacity against bid prices. The plot includes annotations for technologies, market clearing price lines, and company legend.

Parameters:

  • all_bids_sorted (pandas.DataFrame) – Sorted DataFrame containing bid information including capacity and prices

  • demand (float) – Total market demand in MW

  • market_clearing_price (float) – Cleared market price in €/MWh

Returns:

Displays the merit order curve plot

Return type:

None

inputs: Dict = {'bids': {}}
outputs: Dict = {}
parameters: Dict = {'results_dir': 'operator_results'}
states: Dict = {'demand': None, 'market_clearing_price': 0, 'market_results_summary': None}
step(time: int, inputs: dict = None, max_advance: int = 1) → None

Advances the simulation one time step, processes bids, calculates market clearing results and stores state information.

Parameters:

  • time (int) – Current simulation time in hours

  • inputs (dict) – Dictionary containing submitted bids from generators with bid prices and capacities

  • max_advance (int, optional) – Maximum time to advance in hours. Defaults to 1.

Returns:

Next simulation time step in hours, calculated as current time plus time_step_size

Return type:

int

time = None
time_step_size: int = 1