Illuminator Component Models

class illuminator.models.Battery.battery_v3.Battery(**kwargs)

Battery model class for simulating battery charging and discharging behavior.

This class implements a battery model that can simulate charging and discharging cycles, track state of charge, and manage power flows while respecting battery constraints.

Parameters:

max_p (float) – Maximum charging power limit in kW
min_p (float) – Maximum discharging power limit in kW
max_energy (float) – Maximum energy storage capacity in kWh
charge_efficiency (float) – Battery charging efficiency in %
discharge_efficiency (float) – Battery discharging efficiency in %
soc_min (float) – Minimum allowable state of charge in %
soc_max (float) – Maximum allowable state of charge in %

Return type:

None

charge_battery(flow2b: int) → dict

discharge_battery(flow2b: int) → dict

Discharge the battery, calculate the state of charge and return parameter information. Discharge the battery, calculate the state of charge and return parameter information.

This method discharges the battery based on the requested power flow, updates the state of charge (SOC), and returns a dictionary containing the battery’s operational parameters.

Parameters:: flow2b (int) – Power flow requested from the battery (negative value) in kW
Returns:: re_params – Collection of parameters and their respective values: - p_out: Output power from the battery after discharge decision (kW) - p_in: Input power to the battery (kW) - soc: Updated state of charge after battery operation (%) - mod: Operation mode: 0=no action, 1=charge, -1=discharge - flag: Flag indicating battery status: 1=fully charged, -1=fully discharged, 0=available for control Collection of parameters and their respective values: - p_out: Output power from the battery after discharge decision (kW) - p_in: Input power to the battery (kW) - soc: Updated state of charge after battery operation (%) - mod: Operation mode: 0=no action, 1=charge, -1=discharge - flag: Flag indicating battery status: 1=fully charged, -1=fully discharged, 0=available for control
Return type:: dict

inputs: Dict = {'flow2b': 0}

output_power(flow2b: int) → dict

Determine the battery operation mode and power output based on the requested power flow.

This method controls the battery’s operation by determining whether to charge, discharge, or maintain the current state based on the requested power flow and the battery’s state of charge (SOC). Determine the battery operation mode and power output based on the requested power flow.

This method controls the battery’s operation by determining whether to charge, discharge, or maintain the current state based on the requested power flow and the battery’s state of charge (SOC).

Parameters:: flow2b (int) – Power flow requested to/from the battery. Positive for charging, negative for discharging (kW) Power flow requested to/from the battery. Positive for charging, negative for discharging (kW)
Returns:: re_params – Dictionary containing the battery’s operational parameters: - p_out: Output power after charge/discharge decision (kW) - p_in: Input power to the battery (kW) - soc: Updated state of charge (%) - mod: Operation mode (0=no action, 1=charge, -1=discharge) - flag: Battery status (1=fully charged, -1=fully discharged, 0=available)
Return type:: dict

outputs: Dict = {'p_in': 20, 'p_out': 20}

parameters: Dict = {'charge_efficiency': 90, 'discharge_efficiency': 90, 'max_energy': 50, 'max_p': 150, 'min_p': 250, 'soc_max': 80, 'soc_min': 3}

states: Dict = {'flag': -1, 'mod': 0, 'soc': 0}

step(time: int, inputs: dict = None, max_advance: int = 900) → None

Process one simulation step of the battery model.

This method processes the inputs for one timestep, updates the battery state based on the requested power flow, and sets the model outputs and states accordingly.

Parameters:

time (int) – Current simulation time
inputs (dict) – Dictionary containing input values, specifically: - flow2b: Power flow to/from battery (positive=charging, negative=discharging) in kW
max_advance (int, optional) – Maximum time step size in seconds (default 900)

Returns:

Next simulation time step

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.CSV_reader_v3.CSV(**kwargs)

A model for reading time series data from CSV files.

This model reads data from a CSV file line by line, synchronizing with simulation time. The CSV file should contain a header row with column names and a timestamp column.

Parameters:

date_format (str) – Format of the date/time column in the CSV file
delimiter (str) – Column delimiter character in the CSV file (default ‘,’)
datafile (str) – Path to the CSV file to read from

Inputs:

None

Outputs:

next_row (dict) – The data from the current row, with column names as keys

States:

None

finalize() → None: Closes the file object within self.datafile.

init(sid, time_resolution=1, **sim_params)

Initialize the simulator with the ID sid and pass the: time_resolution and additional parameters (sim_params) sent by mosaik. Return the meta data meta.

If your simulator has no sim_params, you don’t need to override this method.

inputs: Dict = {}

outputs: Dict = {'next_row': ''}

parameters: Dict = {'datafile': '', 'date_format': '', 'delimiter': ','}

states: Dict = {}

step(time, inputs, max_advance=900) → None

Perform one step of the simulation.

Parameters:

timeint: The current time of the simulation.
inputsdict: Input values for the simulation step.
max_advanceint: Maximum time the simulator can advance (default is 900 seconds).

Returns:

int: The next simulation time.

time = None

time_step_size: int = 1

class illuminator.models.Gridconnection.grid_connection_v3.GridConnection(**kwargs)

Grid connection model that monitors power flows and sets warning flags for grid congestion.

This model tracks power flows through a grid connection point and sets warning flags when pre-defined capacity limits are exceeded. It uses tolerance and critical thresholds as percentages of the total connection capacity.

Parameters:

connection_capacity (float) – Maximum power capacity of the grid connection (kW)
tolerance_limit (float) – Threshold for warning flag as fraction of connection capacity (e.g. 0.8 = 80%)
critical_limit (float) – Threshold for critical flag as fraction of connection capacity (e.g. 0.9 = 90%)

Inputs:

dump (float) – Power flow through grid connection (kW, negative for export)

Outputs:

None

States:

flag_critical (int) – Flag indicating critical limit exceeded (1) or not (0)
flag_warning (int) – Flag indicating warning limit exceeded (1) or not (0)

check_limits(dump) → dict

Checks if power flow exceeds grid connection limits and sets warning flags.

Parameters:: dump (float) – Power flow to the grid in kW (negative values for export)
Returns:: re_params – Dictionary containing warning flag states
Return type:: dict

inputs: Dict = {'dump': 0}

outputs: Dict = {}

parameters: Dict = {'connection_capacity': None, 'critical_limit': None, 'tolerance_limit': None}

states: Dict = {'flag_critical': None, 'flag_warning': None}

step(time: int, inputs: dict = None, max_advance: int = 900) → None

Performs a single simulation time step by checking grid connection limits.

Parameters:

time (float) – Current simulation time in seconds
inputs (dict) – Dictionary containing input values including ‘dump’ (power flow to grid)
max_advance (int, optional) – Maximum time step advancement, defaults to 900

Returns:

Next simulation time step

Return type:

float

time = None

time_step_size: int = 1

class illuminator.models.Load.load_v3.Load(**kwargs)

Calculates total load demand based on number of houses and input load.

Parameters:

houses (int) – Number of houses that determine the total load demand
output_type (str) – Type of output for consumption calculation (‘energy’ or ‘power’)

Inputs:

load (float) – Incoming energy or power demand per house in kW or kWh

Outputs:

load_dem (float) – Total energy or power consumption for all houses (kWh) over the time step
consumption (float) – Current energy or power consumption based on the number of houses and input load (kWh)

States:

time (int) – Current simulation time in seconds
forecast (None) – Placeholder for future load forecasting functionality

demand(load: float) → dict

Calculates total load demand based on number of houses and input load.

Parameters:: load (float) – Input load per house in kW or kWh depending on output_type
Returns:: re_params – Dictionary containing calculated load demand values
Return type:: dict

inputs: Dict = {'load': 0}

outputs: Dict = {'consumption': 0, 'load_dem': 0}

parameters: Dict = {'houses': 1, 'output_type': 'power'}

states: Dict = {'forecast': None, 'time': None}

step(time: int, inputs: dict = None, max_advance: int = 900) → None

Performs a single simulation time step by calculating load demand.

Parameters:

time (float) – Current simulation time in seconds
inputs (dict) – Dictionary containing input values including ‘load’
max_advance (int, optional) – Maximum time step advancement, defaults to 1

Returns:

Next simulation time step

Return type:

float

time = None

time_step_size: int = 1

class illuminator.models.PV.pv_model_v3.PV(**kwargs)

A PV model that calculates power generation based on environmental conditions.

This model simulates photovoltaic panel performance considering irradiance components, panel orientation, temperature effects, and system losses. It can output either power or energy values.

Parameters:

m_area (float) – Module area of the PV panel in m²
NOCT (float) – Nominal Operating Cell Temperature in °C
m_efficiency_stc (float) – Module efficiency under standard test conditions
G_NOCT (float) – Irradiance at NOCT conditions in W/m²
P_STC (float) – Power output under standard test conditions in W
m_tilt (float) – Module tilt angle in degrees
m_az (float) – Module azimuth angle in degrees
cap (float) – Installed capacity in kW
output_type (str) – Output type (‘power’ or ‘energy’)

Inputs:

G_Gh (float) – Global horizontal irradiance in W/m²
G_Dh (float) – Diffuse horizontal irradiance in W/m²
G_Bn (float) – Direct normal irradiance in W/m²
Ta (float) – Ambient temperature in °C
hs (float) – Solar elevation angle in degrees
FF (float) – Wind speed in m/s
Az (float) – Sun azimuth angle in degrees

Outputs:

pv_gen (float) – PV generation in kW or kWh
total_irr (float) – Total irradiance on tilted surface in W/m²
g_aoi (float) – Total irradiance considering angle of incidence in W/m²

States:

None

Temp_effect() → float

Calculates the temperature-dependent module efficiency. Calculates the temperature-dependent module efficiency.

Takes into account: - Module temperature based on NOCT conditions - Wind speed effects - Temperature coefficient of efficiency Takes into account: - Module temperature based on NOCT conditions - Wind speed effects - Temperature coefficient of efficiency

Returns:: efficiency – Temperature-adjusted module efficiency as a fraction Temperature-adjusted module efficiency as a fraction
Return type:: float

aoi()

Calculates the cosine of the angle of incidence (AOI) between the sun’s rays and the PV module surface.

Takes into account: - Module tilt angle - Sun elevation angle - Sun azimuth angle - Module azimuth angle Calculates the cosine of the angle of incidence (AOI) between the sun’s rays and the PV module surface.

Takes into account: - Module tilt angle - Sun elevation angle - Sun azimuth angle - Module azimuth angle

Returns:: cos_aoi – Cosine of the angle of incidence (AOI) as a fraction Cosine of the angle of incidence (AOI) as a fraction
Return type:: float

diffused_irr() → float

Calculates diffuse irradiance on the tilted PV surface. Calculates diffuse irradiance on the tilted PV surface.

Takes into account: - Sky view factor (SVF) based on module tilt - Diffuse Horizontal Irradiance (DHI) Takes into account: - Sky view factor (SVF) based on module tilt - Diffuse Horizontal Irradiance (DHI)

Returns:: g_diff – Diffuse irradiance on the tilted PV surface in W/m² Diffuse irradiance on the tilted PV surface in W/m²
Return type:: float

direct_irr() → float

Calculates direct beam irradiance on tilted surface. Calculates direct beam irradiance on tilted surface.

Accounts for angle of incidence between sun rays and module surface. Accounts for angle of incidence between sun rays and module surface.

Returns:: g_dir – Direct beam irradiance on tilted surface in W/m² Direct beam irradiance on tilted surface in W/m²
Return type:: float

inputs: Dict = {'Az': 0, 'FF': 0, 'G_Bn': 0, 'G_Dh': 0, 'G_Gh': 0, 'Ta': 0, 'hs': 0}

output() → dict

Calculates PV power or energy output based on environmental conditions.

Takes into account: - Module temperature effects - Inverter and MPPT efficiency - System losses - Total module area - Solar irradiance Calculates PV power or energy output based on environmental conditions.

Takes into account: - Module temperature effects - Inverter and MPPT efficiency - System losses - Total module area - Solar irradiance

Returns:: Dictionary containing: - ‘pv_gen’: PV generation in kW (power) or kWh (energy) - ‘total_irr’: Total irradiance on tilted surface in W/m² <- check Dictionary containing: - ‘pv_gen’: PV generation in kW (power) or kWh (energy) - ‘total_irr’: Total irradiance on tilted surface in W/m² <- check
Return type:: dict

outputs: Dict = {'g_aoi': 0, 'pv_gen': 0, 'total_irr': 0}

parameters: Dict = {'G_NOCT': 0, 'NOCT': 0, 'P_STC': 0, 'cap': 0, 'm_area': 0, 'm_az': 0, 'm_efficiency_stc': 0, 'm_tilt': 0, 'output_type': 'power', 'peak_power': 0, 'sim_start': 0}

reflected_irr() → float

Calculates ground-reflected irradiance on the PV module. Calculates ground-reflected irradiance on the PV module.

Takes into account: - Albedo (reflectivity) of the ground surface - Sky view factor (SVF) based on module tilt - Global Horizontal Irradiance (GHI) Takes into account: - Albedo (reflectivity) of the ground surface - Sky view factor (SVF) based on module tilt - Global Horizontal Irradiance (GHI)

Returns:: g_ref – Ground-reflected irradiance on the PV module in W/m² Ground-reflected irradiance on the PV module in W/m²
Return type:: float

states: Dict = {'pv_gen': 0}

step(time: int, inputs: dict = None, max_advance: int = 900) → None

Step function that updates model state and outputs based on current inputs.

Parameters:

time (int) – Current simulation time
inputs (dict, optional) – Dictionary containing input values
max_advance (int, optional) – Maximum time step size, defaults to 900

Returns:

Next simulation time step

Return type:

int

sun_azimuth()

Getter for the self.sun_az attribute

…

Returns:

sun_azimuth (float) – Sun azimuth angle in degrees, indicating the sun’s position in the horizontal plane.
sun_azimuth (float) – Sun azimuth angle in degrees, indicating the sun’s position in the horizontal plane.

sun_elevation()

Getter for the self.sun_el attribute

…

Returns:

sun_elevation (float) – Solar elevation angle in degrees, indicating the height of the sun in the sky.
sun_elevation (float) – Solar elevation angle in degrees, indicating the height of the sun in the sky.

time = None

time_step_size: int = 1

total_irr() → float

Calculates total irradiance on the tilted PV surface. Calculates total irradiance on the tilted PV surface.

Combines direct beam, diffuse, and ground-reflected irradiance components accounting for module tilt and orientation. Combines direct beam, diffuse, and ground-reflected irradiance components accounting for module tilt and orientation.

Returns:: self.g_aoi – Total irradiance on tilted surface in W/m² Total irradiance on tilted surface in W/m²
Return type:: float

class illuminator.models.Wind.wind_v3.Wind(**kwargs)

A wind turbine model that calculates power generation based on wind speed.

This model simulates wind turbine performance considering wind speed at different heights, power curve characteristics, and system parameters. It can output either power or energy values.

Parameters:

p_rated (float) – Rated power output (kW) at rated wind speed
u_rated (float) – Rated wind speed (m/s)
u_cutin (float) – Cut-in wind speed (m/s)
u_cutout (float) – Cut-out wind speed (m/s)
cp (float) – Coefficient of performance (Betz limit max 0.59)
diameter (float) – Rotor diameter (m)
output_type (str) – Output type (‘power’ or ‘energy’)

Inputs:

u (float) – Wind speed at hub height (m/s)

Outputs:

wind_gen (float) – Wind generation in kW or kWh
u (float) – Adjusted wind speed at 25m height (m/s)

States:

u60 (float) – Wind speed at 60m height (m/s)
u25 (float) – Wind speed at 25m height (m/s)

generation(u: float) → dict

Calculates the final wind power output considering cut-in/out speeds and rated power.

This function determines the actual power output based on the adjusted wind speed, taking into account the turbine’s operational limits such as cut-in speed, rated speed, and cut-out speed.

Parameters:: u (float) – Wind speed at hub height (100m) in m/s
Returns:: Dictionary containing: - wind_gen: Power output in kW or energy output in kWh - u: Adjusted wind speed at 25m height in m/s
Return type:: dict

inputs: Dict = {'u': 0}

outputs: Dict = {'u': 0, 'wind_gen': 0}

parameters: Dict = {'cp': 0.4, 'diameter': 30, 'output_type': 'power', 'p_rated': 500, 'u_cutin': 1, 'u_cutout': 1000, 'u_rated': 100}

powerout = 0

production(u: float) → dict

Calculates the wind power production using the basic wind power equation.

The function accounts for air density, rotor area, and the wind turbine’s coefficient of performance. It also adjusts wind speeds for different heights using logarithmic wind profile equations.

Parameters:: u (float) – Wind speed at hub height (100m) in m/s
Returns:: Dictionary containing: - wind_gen: Power output in kW or energy output in kWh - u: Adjusted wind speed at 25m height in m/s
Return type:: dict

states: Dict = {'u25': 0, 'u60': 10}

step(time: int, inputs: dict = None, max_advance: int = 1) → None

Advances the simulation one time step. :param time: Current simulation time in seconds :type time: float :param inputs: Dictionary containing input values: :type inputs: dict :param - u: Wind speed [m/s] at hub height :type - u: float :param max_advance: Maximum time to advance in seconds. Defaults to 1. :type max_advance: int, optional

Returns:: Next simulation time in seconds
Return type:: float

time = None

time_step_size: int = 1

u25 = 0

u60 = 10