Illuminator Component Models

class illuminator.models.Collector.collector_v3.Collector(**kwargs)

A model for writing time series data to CSV files.

This model writes data to 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 / list) – [list of] Path to the CSV file to read from

• send_row (bool) – If True, sends the entire row as a dictionary under the key ‘row’. If False, sends individual columns as separate states.

Inputs:

file_index (int (optional)) – If multiple files are provided, this input selects which file to read from.

Outputs:

None

States:

• next_row (dict (optional, if send_row is True)) – The next row of data read from the CSV file.

• <column_name> (float (for each column in the CSV file, if send_row is False)) – The value of each column in the current row.

inputs2df(inputs)

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.

unpack_inputs(inputs)

Unpacks input values from connected simulators and processes them based on their message origin.

Parameters:

inputsdict

Dictionary containing input values from connected simulators with their message origin

return_sourcesbool, optional

If True, returns the sorurces of state messages along with their values. Defaults to False

returns:

data – Dictionary containing processed input values, summed for outputs or single values for states

rtype:

dict

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 / list) – [list of] Path to the CSV file to read from

• send_row (bool) – If True, sends the entire row as a dictionary under the key ‘row’. If False, sends individual columns as separate states.

Inputs:

file_index (int (optional)) – If multiple files are provided, this input selects which file to read from.

Outputs:

None

States:

• next_row (dict (optional, if send_row is True)) – The next row of data read from the CSV file.

• <column_name> (float (for each column in the CSV file, if send_row is False)) – The value of each column in the current row.

change_file(file_index) → None

Change the CSV file being read based on the ‘file_index’ input.

finalize() → None

Closes the file object within self.datafile.

go_to_expected_date() → None

go_to_start_date() → None

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.

skip_header()

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.

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.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. It is not module temperature, but cell temperature!!!!

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

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.

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

Returns:

g_dir – 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

Returns:

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)

Returns:

g_ref – 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.

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²

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

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, 'input_type': 'energy', '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.Load.LoadEV.load_EV_v3.LoadEV(**kwargs)

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

demand(power: float, n: int) → dict

Calculates total EV load demand based on power per EV and number of EVs.

Parameters:

• power (float) – Power consumption per EV in kWh per 15-min interval

• n (int) – Number of EVs charging at current time step

Returns:

re_params – Dictionary containing EV load demand and number of EVs

Return type:

dict

inputs: Dict = {'n': 0, 'power': 0}

outputs: Dict = {'load_EV': 0}

parameters: Dict = {'houses_case': None, 'houses_data': None}

states: Dict = {}

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

Performs a single simulation time step by calculating EV load demand.

Parameters:

• time (float) – Current simulation time in seconds

• inputs (dict) – Dictionary containing input values including ‘power’ and ‘n’

• 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.LoadHeatpump.load_heatpump_v3.LoadHeatpump(**kwargs)

Heat pump load model for calculating and scaling demand based on number of houses.

Takes heat pump load input data and scales it proportionally based on the ratio between target and reference number of houses. Supports direct passthrough when house numbers match.

Parameters:

• houses_case (int) – Target number of houses to scale demand for

• houses_data (int) – Reference number of houses in the input data

Returns:

Dictionary containing scaled heat pump load values

Return type:

dict

demand(hp_load: float) → dict

Calculates total heat pump load demand from input load and scales based on house ratio.

Parameters:

hp_load (float) – Input heat pump load in kW for reference number of houses

Returns:

re_params – Dictionary containing calculated heat pump load value scaled to target houses

Return type:

dict

inputs: Dict = {'hp_load': 0}

outputs: Dict = {'load_HP': 0}

parameters: Dict = {'houses_case': 1, 'houses_data': None}

states: Dict = {}

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

Performs a single simulation time step by calculating scaled heat pump load demand.

Parameters:

• time (int) – Current simulation time in seconds

• inputs (dict) – Dictionary containing input values including heat pump load data

• max_advance (int, optional) – Maximum time step advancement in seconds, defaults to 900

Returns:

Next simulation time step in seconds

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.ElectricVehicle.EV.EV(**kwargs)

A class to represent an Electric Vehicle (EV) charging model. This class provides methods to simulate the charging process of an EV battery.

parameters

Dictionary containing EV parameters such as end phases of charging, maximum power, and battery capacity.

Type:

dict

inputs

Dictionary containing input variables like available power for charging.

Type:

dict

outputs

Dictionary containing calculated outputs like power demand during charging.

Type:

dict

states

Dictionary containing the state variables of the EV model, such as state of charge (SOC) and desired SOC.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

step(time, inputs, max_advance=900)

Simulates one time step of the EV charging model.

charge(available_power, max_advance)

Implements the charging curve and calculates the power demand based on available power and battery state.

charge()

inputs: Dict = {'load_in': 0}

outputs: Dict = {'demand': 0, 'presence': 0}

parameters: Dict = {'battery_cap': 0, 'end_initial_phase': 0, 'end_mid_phase': 0, 'fast': False, 'max_power': 0}

states: Dict = {'desired_soc': 0, 'soc': 0}

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

Simulates one time step of the EV model.

This method processes the inputs for one timestep, updates the state of charge (SOC) based on the charging process, and sets the model outputs accordingly.

Parameters:

• time (int) – Current simulation time

• inputs (dict) – Dictionary containing input values, specifically: - available_power: Power available for charging [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.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.Buffer.buffer.H2Buffer(**kwargs)

A class to represent an H2 Buffer model. This class provides methods to simulate the hydrogen flow through the buffer.

parameters

Dictionary containing buffer parameters such as minimum and maximum state of charge, charge and discharge efficiency, and total capacity.

Type:

dict

inputs

Dictionary containing input variables like flow to the hydrogen buffer.

Type:

dict

outputs

Dictionary containing calculated outputs like flow into and out of the buffer, state of charge, operating mode, and buffer status flag.

Type:

dict

states

Dictionary containing the state variables of the buffer model.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

step(time, inputs, max_advance=1)

Simulates one time step of the hydrogen buffer model.

operation(h2_in, desired_out)

Physically limits the in and outflow of hydrogen based on the design parameters

cap_calc()

Calculates the amount of hydrogen that can be charged ad discharged from the buffers models (external pov)

cap_calc()

Function to determine the amount of h2 that can still be stored or discharged. …

Parameters:

• h2_in (float) – Input to the buffer [kg/timestep]

• desired_out (float) – Desired output flow [kg/timestep]

Returns:

result – Collection of parameters and their respective values

Return type:

dict

inputs: Dict = {'desired_out': 0, 'h2_in': 0}

limit_input_flow(h2_in: float) → float

Limits the input flow to the buffer based on the maximum and minimum flow rates.

Parameters:

h2_in (float) – Input flow to the buffer [kg/timestep]

Returns:

Limited input flow [kg/timestep]

Return type:

float

operation(h2_in: float, desired_out: float) → dict

Control for the buffer (physical). Outputs the actual flow. …

Parameters:

• h2_in (float) – Input to the buffer [kg/timestep]

• desired_out (float) – Desired output flow [kg/timestep]

Returns:

result – Collection of parameters and their respective values

Return type:

dict

outputs: Dict = {'actual_h2_in': 0, 'h2_out': 0, 'overflow': 0}

parameters: Dict = {'h2_capacity_tot': 100, 'h2_charge_eff': 100, 'h2_discharge_eff': 100, 'h2_soc_max': 100, 'h2_soc_min': 0, 'max_flow_rate_in': 10, 'max_flow_rate_out': 10, 'min_flow_rate_in': 0, 'min_flow_rate_out': 0}

states: Dict = {'available_h2': 0, 'flag': 0, 'free_capacity': 0, 'soc': 0}

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

Simulates one time step of the hydrogen buffer model.

This method processes the inputs for one timestep, updates the hydrogen buffer state based on the hydrogen flow, and sets the model outputs accordingly.

Parameters:

• time (int) – Current simulation time

• inputs (dict) – Dictionary containing input values, specifically: - h2_in: Hydrogen flow that appears to the input of the buffer [kg/timestep] - desired_out: The desired output flow of the buffer [kg/timestep]

• max_advance (int, optional) – Maximum time step size (default 900)

Returns:

Next simulation time step

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.Electrolyzer.electrolyzer_v3.Electrolyzer(**kwargs)

generate(flow2e)

Calculates the hydrogen produced per timestep taking the maximum electric power into account.

…

Parameters:

• flow2e (float) – Input power flow [kW]

• eff (float) – Electrolyzer efficiency [%]

• hhv (float) – Higher heating value of hydrogen [kJ/mol]

• mmh2 (float) – Molar mass of hydrogen [g/mol]

Returns:

h_out – Output flow of hyrdgen [kg/timestep]

Return type:

float

generate_setpoint(desired_out)

Calculates the hydrogen produced per timestep taking the maximum electric power into account.

…

Parameters:

• desired_out (float) – Desired output flow of hydrogen [kg/h]

• eff (float) – Electrolyzer efficiency [%]

• hhv (float) – Higher heating value of hydrogen [kJ/mol]

• mmh2 (float) – Molar mass of hydrogen [g/mol]

Returns:

h_out – Output flow of hyrdgen [kg/timestep]

Return type:

float

inputs: Dict = ({'desired_out': 30},)

kw_to_kg_per_h(power_kw: float) → float

Calculate hydrogen production rate (kg/h) from a given power (kW).

Parameters:

power_kw (float) – Electrical power in kilowatts.

Returns:

kg_per_h – Hydrogen production rate in kilograms per hour.

Return type:

float

kwh_to_kg(kwh)

Converts kWh to kg of hydrogen produced.

…

Parameters:

kwh (float) – Energy in kWh

Returns:

kg – Hydrogen produced in kg

Return type:

float

outputs: Dict = ({'h_gen': 0, 'power_consumption': 0},)

parameters: Dict = ({'e_eff': 70, 'max_p_in': 10, 'max_p_ramp_rate': 10},)

ramp_lim(flow2e)

Limits the input power by the maximimum ramp up limits.

…

Parameters:

flow2e (float) – Input power flow [kW]

Returns:

power_in – Input power after implemeting ramping limits [kW]

Return type:

float

states: Dict = ({},)

step(time, inputs, max_advance=1) → None

Defines the computations that need to be performed in each simulation step

Parameters:

• time (int) – The current time of the simulation.

• inputs (dict) – The inputs to the model.

• max_advance (int) – Time until the simulator can safely advance its internal time without creating a causality error. Optional in most cases.

Returns:

The new time of the simulation.

Return type:

int

time = None

class illuminator.models.Electrolyzer.ZZE_v3.ZZE(**kwargs)

buffer_operation(h2_in: float, desired_out: float) → dict

Control for the buffer (physical). Outputs the actual flow. …

Parameters:

• h2_in (float) – Input to the buffer [kg/timestep]

• desired_out (float) – Desired output flow [kg/timestep]

Returns:

result – Collection of parameters and their respective values

Return type:

dict

cap_calc()

Function to determine the amount of h2 that can still be stored or discharged. …

Parameters:

• h2_in (float) – Input to the buffer [kg/timestep]

• desired_out (float) – Desired output flow [kg/timestep]

Returns:

result – Collection of parameters and their respective values

Return type:

dict

generate(flow2e)

Calculates the hydrogen produced per timestep taking the maximum electric power into account.

…

Parameters:

• flow2e (float) – Input power flow [kW]

• eff (float) – Electrolyzer efficiency [%]

• hhv (float) – Higher heating value of hydrogen [kJ/mol]

• mmh2 (float) – Molar mass of hydrogen [g/mol]

Returns:

h_out – Output flow of hyrdgen [kg/timestep]

Return type:

float

generate_setpoint(desired_out)

Calculates the hydrogen produced per timestep taking the maximum electric power into account.

…

Parameters:

• desired_out (float) – Desired output flow of hydrogen [kg/h]

• eff (float) – Electrolyzer efficiency [%]

• hhv (float) – Higher heating value of hydrogen [kJ/mol]

• mmh2 (float) – Molar mass of hydrogen [g/mol]

Returns:

h_out – Output flow of hyrdgen [kg/timestep]

Return type:

float

inputs: Dict = {'desired_out': 30, 'h2_in': 0}

kg_to_kwh(kg)

Converts kg of hydrogen produced to kWh.

…

Parameters:

kg (float) – Hydrogen produced in kg

Returns:

kwh – Energy in kWh

Return type:

float

kw_to_kg_per_h(power_kw: float) → float

Calculate hydrogen production rate (kg/h) from a given power (kW).

Parameters:

power_kw (float) – Electrical power in kilowatts.

Returns:

kg_per_h – Hydrogen production rate in kilograms per hour.

Return type:

float

kwh_to_kg(kwh)

Converts kWh to kg of hydrogen produced.

…

Parameters:

kwh (float) – Energy in kWh

Returns:

kg – Hydrogen produced in kg

Return type:

float

limit_input_flow(h2_in: float) → float

Limits the input flow to the buffer based on the maximum and minimum flow rates.

Parameters:

h2_in (float) – Input flow to the buffer [kg/timestep]

Returns:

Limited input flow [kg/timestep]

Return type:

float

outputs: Dict = {'actual_h2_in': 0, 'h2_out': 0, 'h_gen': 0, 'overflow': 0, 'power_consumption': 0}

parameters: Dict = {'e_eff': 70, 'h2_capacity_tot': 100, 'h2_charge_eff': 100, 'h2_discharge_eff': 100, 'h2_soc_max': 100, 'h2_soc_min': 0, 'max_flow_rate_in': 10, 'max_flow_rate_out': 10, 'max_p_in': 10, 'max_p_ramp_rate': 10, 'min_flow_rate_in': 0, 'min_flow_rate_out': 0}

ramp_lim(flow2e)

Limits the input power by the maximimum ramp up limits.

…

Parameters:

flow2e (float) – Input power flow [kW]

Returns:

power_in – Input power after implemeting ramping limits [kW]

Return type:

float

states: Dict = {'available_h2': 0, 'flag': 0, 'free_capacity': 0, 'soc': 0}

step(time, inputs, max_advance=1) → None

Defines the computations that need to be performed in each simulation step

Parameters:

• time (int) – The current time of the simulation.

• inputs (dict) – The inputs to the model.

• max_advance (int) – Time until the simulator can safely advance its internal time without creating a causality error. Optional in most cases.

Returns:

The new time of the simulation.

Return type:

int

time = None

class illuminator.models.Thermolyzer.thermolyzer_v3.Thermolyzer(**kwargs)

Thermolyzer model class for simulating a thermolyzer that converts biomass and electricity into hydrogen.

Parameters:

• eff (float) – Thermolyzer efficiency as a percentage [%]

• C_bio_h2 (float) – Conversion factor from biomass to hydrogen [-]

• CO_2 (float) – Absorption factor carbondioxide per h2 produced [-]

• C_Eelec_h2 (float) – Conversion factor electrical energy to hydrogen mass [kWh/kg]

• max_ramp_up (float) – Maximum ramp up in power per timestep [kW/timestep]

• max_p_in (float) – Maximum input power [kW]

Return type:

None

generate(m_bio: float, flow2t: float, max_advance: int = 900) → float

Generate hydrogen based on biomass and power input.

This method calculates the hydrogen production based on the available biomass and electrical power input, considering the efficiency and ramp rate constraints.

Parameters:

• m_bio (float) – Biomass input in kg/timestep

• flow2t (float) – Power input to the thermolyzer in kW

• max_advance (int, optional) – Maximum time step size in seconds (default 900)

Returns:

Hydrogen production in kg/timestep

Return type:

float

generate_setpoint(m_bio: float, desired_out: float, max_advance: int = 900) → float

Generate hydrogen based on biomass and power input.

This method calculates the hydrogen production based on the available biomass and electrical power input, considering the efficiency and ramp rate constraints.

Parameters:

• m_bio (float) – Biomass input in kg/timestep

• flow2t (float) – Power input to the thermolyzer in kW

• max_advance (int, optional) – Maximum time step size in seconds (default 900)

Returns:

Hydrogen production in kg/timestep

Return type:

float

hhv = 286.6

inputs: Dict = ({'biomass_in': 0, 'desired_out': 30},)

mmh2 = 2.02

outputs: Dict = ({'CO2_out': 0, 'h_gen': 0, 'power_consumption': 0},)

parameters: Dict = ({'C_CO_2': 10, 'C_Eelec_h2': 11.5, 'C_bio_h2': 30, 'eff': 60, 'max_p_in': 10000, 'max_ramp_up': 60},)

ramp_lim(p_in: float, max_advance: int) → float

Limits the thermolyzer input power based on ramp rate constraints.

…

Parameters:

p_in (float) – Desired power input to the thermolyzer [kW]

Returns:

Adjusted power input after applying ramp rate constraints [kW]

Return type:

float

states: Dict = {}

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

Process one simulation step of the thermolyzer model.

This method processes the inputs for one timestep and sets the model outputs and states accordingly.

Parameters:

• time (int) – Current simulation time

• inputs (dict) – Dictionary containing input values, specifically: - biomass_in: Biomass input in kg/timestep - flow2t: Power input to the thermolyzer in kW

• max_advance (int, optional) – Maximum time step size in seconds (default 900)

Returns:

Next simulation time step

Return type:

int

time = None

class illuminator.models.Compressor.compressor_v3.Compressor(**kwargs)

A class to represent a Compressor model. This class provides methods to simulate the compression of hydrogen gas.

parameters

Dictionary containing compressor parameters such as input pressure, output pressure, ambient temperature, and compressor efficiency.

Type:

dict

inputs

Dictionary containing input variables like hydrogen flow to the compressor.

Type:

dict

outputs

Dictionary containing calculated outputs like hydrogen flow from the compressor, power required for compression, and volumetric output flow.

Type:

dict

states

Dictionary containing the state variables of the compressor model.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

hhv

Higher heating value of hydrogen [kJ/mol].

Type:

float

mmh2

Molar mass of hydrogen (H2) [gram/mol].

Type:

float

R

Characteristic gas constant [J/mol*K].

Type:

float

gamma

Specific heat ratio [-].

Type:

float

e_grav_h2

Gravimetric energy density of hydrogen [J/kg].

Type:

float

max_power_in

the maximum input power of the compressor [kW]

Type:

float

step(time, inputs, max_advance=900)

Simulates one time step of the compressor model.

power_req(flow, p_in, p_out, T_amb, max_advance)

Calculates the power required to compress the hydrogen and limits the output flow and power based on this required power.

new_density(p, T)

Calculates the new density of hydrogen after compression.

find_z_val(press, temp)

Finds the Z value needed to compute the new density.

R = 8.314

e_grav_h2 = 120000000.0

find_z_val(press: float, temp: float) → float

Finds the Z value needed to compute the new density.

…

Parameters:

• press (float) – Compressor output pressure [bar]

• temp (float) – Temperature of operation [K]

Returns:

z_val – The Z value that best matches the given pressure and temperature

Return type:

float

gamma = 1.41

hhv = 286.6

inputs: Dict = ({'flow2c': 0},)

mmh2 = 2.02

new_density(p: float, T: float) → float

Calculates and outputs the new density of h2 after compression

…

Parameters:

• p (float) – Output pressure [bar]

• T (float) – Temperature of operation [K]

Returns:

density – The new found density after compression [kg/m3]

Return type:

float

outputs: Dict = ({'flow_from_c': 0},)

parameters: Dict = ({'T_amb': 293.15, 'compressor_eff': 99, 'max_power_in': 10, 'p_in': 30, 'p_out': 500},)

power_req(flow: float, p_in: float, p_out: float, T_amb: float) → dict

Calculates the power required to compress the hydrogen and limits the output flow and power based on this required power.

…

Parameters:

• flow (float) – Hydrogen flow to the compressor [kg/timestep]

• p_in (float) – Input pressure [bar]

• p_out (float) – Output pressure [bar]

• T_amb (float) – Ambient temperature [K]

Returns:

power_in – Power required for compression [kW]

Return type:

float

states: Dict = {'power_req': 0, 'volume_flow_out': 0}

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

Simulates one time step of the compressor model.

This method processes the inputs for one timestep, updates the compressor state based on the hydrogen flow, and sets the model outputs accordingly.

Parameters:

• time (int) – Current simulation time

• inputs (dict) – Dictionary containing input values, specifically: - flow2c: Hydrogen flow to the compressor in kg/timestep

• max_advance (int, optional) – Maximum time step size (default 1)

Returns:

Next simulation time step

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.H2demand.h2demand_v3.H2demand(**kwargs)

A class to represent an H2demand model. This class provides methods to simulate the demand of hydrogen gas.

parameters

Dictionary containing model parameters such as the number of demand units.

Type:

dict

inputs

Dictionary containing input variables like the demand of hydrogen mass per timestep.

Type:

dict

outputs

Type:

dict

states

Dictionary containing the state variables of the demand model.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

step(time, inputs, max_advance=1)

Simulates one time step of the demand model.

demand(demand)

Calculates the total demand given the amount of equally sized units.

h2demand(demand: float) → float

Calculates the total demand given the amount of equally sized units

…

Parameters:

demand (float) – demand of h2 for each timestep [kg/timestep]

Returns:

tot_dem – Total demand of h2 [kg/timestep]

Return type:

float

inputs: Dict = {'demand': 0}

outputs: Dict = {}

parameters: Dict = {'units': 1}

states: Dict = {'tot_dem': 0}

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

Simulates one time step of the H2demand model.

This method processes the inputs for one timestep, updates the demand state based on the hydrogen demand, and sets the model outputs accordingly.

Parameters:

• time (int) – Current simulation time

• inputs (dict) – Dictionary containing input values, specifically: - demand: Hydrogen demand in kg/timestep

• max_advance (int, optional) – Maximum time step size (default 1)

Returns:

Next simulation time step

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.H2pipeline.h2pipeline.Pipeline(**kwargs)

A class to represent a Pipeline model. This class provides methods to simulate the flow of hydrogen gas through a pipeline.

parameters

Dictionary containing pipeline parameters such as cross-sectional area, input pressure, ambient temperature, pipe thickness, and pipe roughness.

Type:

dict

inputs

Dictionary containing input variables like hydrogen flow into the pipeline and input pressure.

Type:

dict

outputs

Dictionary containing calculated outputs like hydrogen flow out of the pipeline and output pressure.

Type:

dict

states

Dictionary containing the state variables of the pipeline model.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

hhv

Higher heating value of hydrogen [kJ/mol].

Type:

float

mmh2

Molar mass of hydrogen (H2) [gram/mol].

Type:

float

R

Characteristic gas constant [J/mol*K].

Type:

float

gamma

Specific heat ratio [-].

Type:

float

e_grav_h2

Gravimetric energy density of hydrogen [J/kg].

Type:

float

step(time, inputs, max_advance=1)

Simulates one time step of the pipeline model.

output_flow(flow_in, density)

Calculates the output flow (mass) given the properties of the pipeline and hydrogen.

permeabilty_coef(press)

Reads the permeability coefficient of hydrogen in HDPE pipes from a table, provided the pressure of the hydrogen.

density(p, T)

Calculates and outputs the density of hydrogen provided pressure and temperature.

find_z_val(press, temp)

Finds the Z value needed to compute the density.

output_pressure(flow_in, density)

Calculates the output pressure given the properties of the pipeline and hydrogen.

viscosity(T)

Reads the viscosity of hydrogen from a table provided the temperature.

R = 8.314

density(p: float, T: float) → float

Calculates and outputs the density of h2 provided pressure and temperature

…

Parameters:

• p (float) – Pressure [bar]

• T (float) – Temperature of operation [K]

Returns:

density – The new found density after compression [kg/m3]

Return type:

float

e_grav_h2 = 120000000.0

find_z_val(press: float, temp: float) → float

Finds the Z value needed to compute the density.

…

Parameters:

• press (float) – Compressor utput pressure [bar]

• temp (float) – Temperature of operation [K]

Returns:

z_val – The Z value that best matches the given pressure and temperature

Return type:

float

gamma = 1.41

hhv = 286.6

inputs: Dict = ({'flow_in': 0, 'pressure_in': 0},)

mmh2 = 2.02

output_flow(flow_in: float, density: float, pressure_in: float) → float

Calculates the output flow (mass) given the properties of the pipeline and hydrogen.

…

Parameters:

• flow_in (float) – Input flow [kg/timestep]

• density (float) – density of the hydrogen [kg/m3]

Returns:

flow_out – Input flow [kg/timestep]

Return type:

float

output_pressure(flow_in: float, density: float, pressure_in: float) → float

Calculates the output pressure [bar] given the properties of the pipeline and hydrogen.

…

Parameters:

flow_in (float) – Input flow [kg/timestep]

Returns:

p_out – Output pressure [bar]

Return type:

float

outputs: Dict = ({'flow_out': 0},)

parameters: Dict = ({'A': 2, 'L': 100, 'T_amb': 293.15, 'd': 0.01, 'eps': 1.5e-06, 'p_outer': 1},)

permeabilty_coef(press: float) → float

Reads the permeability coefficient of hydrogen in HDPE pipes from a table, provided the pressure of the hydrogen. …

Parameters:

p (float) – Pressure of the hydrogen [bar]

Returns:

P – Permeability coefficient of hydrogen in HDPE pipe [cm3*cm/cm2*s*Pa]

Return type:

float

states: Dict = {'press_out': 0}

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

Simulates one time step of the pipeline model.

This method processes the inputs for one timestep, updates the pipeline state based on the hydrogen flow, and sets the model outputs accordingly.

Parameters:

• time (int) – Current simulation time

• inputs (dict) – Dictionary containing input values, specifically: - flow_in: Hydrogen flow into the pipeline in kg/timestep - pressure_in: Input pressure of the hydrogen in bar

• max_advance (int, optional) – Maximum time step size (default 900)

Returns:

Next simulation time step

Return type:

int

time = None

time_step_size: int = 1

viscosity(T: float) → float

Reads the viscosity of hydrogen from a table provided the temperature. …

Parameters:

T (float) – Temperature [K]

Returns:

mu – Visosity of hydrogen [Pa s]

Return type:

float

class illuminator.models.H2storage.h2storage_v3.H2Storage(**kwargs)

A class to represent an H2 Storage model. This class provides methods to simulate the charging and discharging of hydrogen storage.

parameters

Dictionary containing storage parameters such as minimum and maximum state of charge, charge and discharge efficiency, and total capacity.

Type:

dict

inputs

Dictionary containing input variables like flow to the hydrogen storage.

Type:

dict

outputs

Dictionary containing calculated outputs like flow into and out of the storage, state of charge, operating mode, and storage status flag.

Type:

dict

states

Dictionary containing the state variables of the storage model.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

step(time, inputs, max_advance=1)

Simulates one time step of the hydrogen storage model.

discharge(flow2h2storage)

Simulates the discharging process based on the state of charge and the incoming flow.

charge(flow2h2storage)

Simulates the charging process based on the state of charge and the incoming flow.

output_flow(flow2h2storage, soc)

Controller that determines to charge, discharge, or do nothing based on the desired flow.

charge(flow2h2storage)

Simulates the charging process based on the soc and the incoming flow. Returns parameters based on the capacbilities of the h2 storage.

…

Parameters:

flow2h2storage (float) – Desired output flow (positive) [kg/timestep]

Returns:

re_params – Collection of parameters and their respective values

Return type:

dict

discharge(flow2h2storage: float) → dict

Simulates the discharging process based on the soc and the incoming flow. Returns parameters based on the capacbilities of the h2 storage

…

Parameters:

flow2h2storage (float) – Desired output flow (negative) [kg/timestep]

Returns:

re_params – Collection of parameters and their respective values

Return type:

dict

inputs: Dict = {'flow2h2storage': 0}

output_flow(flow2h2storage: float) → dict

Controller that determines to charge, discharge, or do nothing based on the desired flow. Outputs the actual flow.

…

Parameters:

flow2h2storage (float) – Desired output flow [kg/timestep]

Returns:

re_params – Collection of parameters and their respective values

Return type:

dict

outputs: Dict = {'h2_in': 0, 'h2_out': 0}

parameters: Dict = {'h2_capacity_tot': 100, 'h2_charge_eff': 100, 'h2_discharge_eff': 100, 'h2_soc_max': 100, 'h2_soc_min': 0, 'max_h2': 10, 'min_h2': -10}

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

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

Simulates one time step of the hydrogen storage model.

This method processes the inputs for one timestep, updates the hydrogen storage state based on the hydrogen flow, and sets the model outputs accordingly.

Parameters:

• time (int) – Current simulation time

• inputs (dict) – Dictionary containing input values, specifically: - flow2h2storage: Hydrogen flow to the storage in kg/timestep

• max_advance (int, optional) – Maximum time step size (default 900)

Returns:

Next simulation time step

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.H2valve.h2valve_v3.H2Valve(**kwargs)

A class to represent a Valve model for controlling hydrogen flow in a system. This class provides methods to manage the flow of hydrogen through the valve.

parameters

Dictionary containing valve parameters like efficiency.

Type:

dict

inputs

Dictionary containing inputs like hydrogen input flow and fraction of flow allowed through output 1.

Type:

dict

outputs

Dictionary containing calculated outputs like hydrogen flow rates through outputs 1 and 2.

Type:

dict

states

Dictionary containing the state variables of the system.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

__init__(**kwargs)

Initializes the Valve model with the provided parameters.

step(time, inputs, max_advance)

Simulates one time step of the Valve model.

calc_flow(h2_in, ratio1, ratio2, ratio3)

Calculates the flow of hydrogen through the valve based on the input flow and fraction.

calc_flow(h2_in: float, ratio1: float, ratio2: float, ratio3: float) → dict

Calculate the flow through the valve.

Parameters:

• h2_in (float) – Hydrogen input flow rate.

• ratio1 (float) – Fraction of the flow that is allowed to pass through output 1.

• ratio2 (float) – Fraction of the flow that is allowed to pass through output 2.

• ratio3 (float) – Fraction of the flow that is allowed to pass through output 3.

Returns:

Dictionary containing the calculated outputs like hydrogen flow rates through outputs 1 and 2.

Return type:

dict

inputs: Dict = {'h2_in': 0, 'ratio1': 0, 'ratio2': 0, 'ratio3': 0}

outputs: Dict = {'out1': 0, 'out2': 0, 'out3': 0}

parameters: Dict = {'valve_eff': 100}

states: Dict = {}

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

Simulates one time step of the Valve model.

Parameters:

• time (int) – Current simulation time.

• inputs (dict) – Dictionary containing inputs like wind/solar generation, load demand, and storage states.

• max_advance (int) – Maximum time step size for the simulation.

time = None

time_step_size: int = 1

class illuminator.models.H2_joint.H2_joint_v3.H2Joint(**kwargs)

A class to represent a Valve model for controlling hydrogen flow in a system. This class provides methods to manage the flow of hydrogen through the joint.

parameters

Dictionary containing joint parameters like efficiency.

Type:

dict

inputs

Dictionary containing inputs like hydrogen input flow and fraction of flow allowed through output 1.

Type:

dict

outputs

Dictionary containing calculated outputs like hydrogen flow rates through outputs 1 and 2.

Type:

dict

states

Dictionary containing the state variables of the system.

Type:

dict

time_step_size

Time step size for the simulation.

Type:

int

time

Current simulation time.

Type:

int or None

__init__(**kwargs)

Initializes the Valve model with the provided parameters.

step(time, inputs, max_advance)

Simulates one time step of the Valve model.

calc_flow(h2_in, frac)

Calculates the flow of hydrogen through the joint based on the input flow and fraction.

calc_flow(h2_in_1: float, h2_in_2: float) → dict

Calculate the flow through the joint.

Parameters:

• h2_in_1 (float) – Hydrogen input flow from input 1.

• h2_in_2 (float) – Hydrogen input flow from input 2.

• frac (float) – Fraction of the flow that is allowed to pass through output 1.

Returns:

Dictionary containing the calculated outputs like hydrogen output flow.

Return type:

dict

inputs: Dict = {'h2_in_1': 0, 'h2_in_2': 0}

outputs: Dict = {'out': 0}

parameters: Dict = {'joint_eff': 100}

states: Dict = {}

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

Simulates one time step of the Valve model.

Parameters:

• time (int) – Current simulation time.

• inputs (dict) – Dictionary containing inputs like wind/solar generation, load demand, and storage states.

• max_advance (int) – Maximum time step size for the simulation.

time = None

time_step_size: int = 1

class illuminator.models.H2controller.H2_controller_v3.H2Controller(**kwargs)

A class to represent a Controller model for a hybrid renewable energy system. This class provides methods to manage power flows between renewable sources, battery storage, and hydrogen systems.

Attributes parameters : dict

Dictionary containing control parameters like battery and hydrogen storage limits, and fuel cell efficiency.

inputsdict

Dictionary containing inputs like wind/solar generation, load demand, and storage states.

outputsdict

Dictionary containing calculated outputs like power flows to battery/electrolyzer and hydrogen production.

statesdict

Dictionary containing the state variables of the system.

time_step_sizeint

Time step size for the simulation.

timeint or None

Current simulation time.

Methods __init__(**kwargs)

Initializes the Controller model with the provided parameters.

step(time, inputs, max_advance)

Simulates one time step of the H2Controller model.

control(demand1, demandt, thermolyzer_out, h2_soc1, h2_soc2)

Manages hydrogen flows based on generation, demand and storage.

store_rest(rest, valve1_ratio1, valve1_ratio3, available_storage1, available_storage2, thermolyzer_out)

Stores the excess hydrogen.

control(demand1: float, demand2: float, thermolyzer_out: float, h2_soc1: float, h2_soc2: float) → dict

This function executes the control operation. It prioritises direct supply from the thermolzyer and adapts the valve ratios accordingly. In case the storages must be used, they are discharges in such a way that they are equally exploited, again, adapting the valves accordingly. When there is a surplus of hydrogen the two storages are charged to have the same soc.

Parameters:

• demand1 (float) – Demand at low pressure [kg/timestep]

• demand2 (float) – Demand at high pressure [kg/timestep]

• thermolyzer_out (float) – Production of the thermolyzer [kg/timestep]

• h2_soc1 (float) – State of charge of low pressure storage [%]

• h2_soc2 (float) – State of charge of high pressure storage [%]

Returns:

results – Dictionary containing parameters: - flow2h2storage1: flow required as discharge from the low pressure storage [kg/timestep] - flow2h2storage2: flow required as discharge from the high pressure storage [kg/timestep] - dump: over- or underproduced hydrogen in the system [kg/timestep] - valve1_ratio1: ratio of incoming hydrogen to thermolyzer storage1 [%] - valve1_ratio2: ratio of incoming hydrogen to thermolyzer demand1 [%] - valve1_ratio3: ratio of incoming hydrogen from thermolyzer to the compressor [%] - valve2_ratio1: ratio of incoming hydrogen from compressor to demand2 [%] - valve2_ratio2: ratio of incoming hydrogen from compressor to storage2 [%] - valve2_ratio3: unused outlet of the second valve (set to 0) [%]

Return type:

dict

inputs: Dict = {'demand1': 0, 'demand2': 0, 'h2_soc1': 0, 'h2_soc2': 0, 'thermolyzer_out': 0}

outputs: Dict = {'dump': 0, 'flow2h2storage1': 0, 'flow2h2storage2': 0}

parameters: Dict = {'size_storage1': 0, 'size_storage2': 0}

states: Dict = {'valve1_ratio1': 0, 'valve1_ratio2': 0, 'valve1_ratio3': 0, 'valve2_ratio1': 0, 'valve2_ratio2': 0, 'valve2_ratio3': 0}

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

Advances the simulation one time step.

Parameters:

• time (int) – Current simulation time.

• inputs (dict, optional) – Dictionary containing input values: - demand1 (float): Demand for hydrogen from unit 1 [kg/timestep] - demand2 (float): Demand for hydrogen from unit 2 [kg/timestep] - thermolyzer_out (float): Hydrogen output from the thermolyzer [kg/timestep] - compressor_out (float): Hydrogen output from the compressor [kg/timestep] - h2_soc1 (float): Hydrogen storage 1 state of charge [%] - h2_soc2 (float): Hydrogen storage 2 state of charge [%]

• max_advance (int, optional) – Maximum time to advance. Defaults to 900.

Returns:

Next simulation time.

Return type:

int

store_rest(rest: float, valve1_ratio1: float, valve1_ratio3: float, available_storage1: float, available_storage2: float, thermolyzer_out: float)

This function handles the excess production in the system and stores it in the two storages. The logic equalizes the state of charge of both storages and adapts the valveratios accordingly.

Parameters:

• rest (float) – The excess hydrogen that needs to be stored [kg/timestep]

• valve1_ratio1 (float) – Ratio of incoming hydrogen to thermolyzer storage1 [%]

• valve1_ratio3 (float) – Ratio of incoming hydrogen from thermolyzer to the compressor [%]

• available_storage1 (float) – The amount of of hydrogen present in the low pressure storage [kg]

• available_storage2 (float) – The amount of of hydrogen present in the high pressure storage [kg]

• thermolyzer_out (float) – Production of the thermolyzer [kg/timestep]

Returns:

• valve1_ratio1 (float) – ratio of incoming hydrogen to thermolyzer storage1 [%]

• valve1_ratio3 (float) – ratio of incoming hydrogen from thermolyzer to the compressor [%]

time = None

time_step_size: int = 1

class illuminator.models.H2controller.H2_controller2.H2Controller2(**kwargs)

A class to represent a Controller model for a hybrid renewable energy system. This class provides methods to manage flows in and out of a buffer.

Attributes parameters : dict

Dictionary containing control parameters like battery and hydrogen storage limits, and fuel cell efficiency.

inputsdict

Dictionary containing inputs like wind/solar generation, load demand, and storage states.

outputsdict

Dictionary containing calculated outputs like power flows to battery/electrolyzer and hydrogen production.

statesdict

Dictionary containing the state variables of the system.

time_step_sizeint

Time step size for the simulation.

timeint or None

Current simulation time.

Methods __init__(**kwargs)

Initializes the Controller model with the provided parameters.

step(time, inputs, max_advance)

Simulates one time step of the H2Controller2 model.

control(demand1, demandt, thermolyzer_out, h2_soc1, h2_soc2)

Manages hydrogen flows based on generation, demand and storage.

control(demand1: float, demand2: float, thermolyzer_out: float, buffer_available_h2: float, buffer_free_capacity: float) → dict

This function executes the control operation. Based on how full the hydrogen buffer is and the combination of demand and production, it controls the buffer.

Parameters:

• demand1 (float) – Demand [kg/timestep]

• demand2 (float) – Demand [kg/timestep]

• thermolyzer_out (float) – Production of the thermolyzer [kg/timestep]

• buffer_available_h2 (float) – Amount of hydrogen that can be discharged from the buffer [kg]

• buffer_free_capacity (float) – Amount of hydrogen that can be charged before reaching full soc [kg]

Returns:

results – Dictionary containing parameters: - dump: over hydrogen in the system [kg/timestep] - valve1_ratio1: ratio of incoming hydrogen going to demand 1 [%] - valve1_ratio2: ratio of incoming hydrogen going to demand 2 [%] - valve1_ratio3: unused [%] - buffer_in: hydrogen that appears at the input of the buffer [kg/timestep] - desired_out: amount of hydrogen demanded at the output of the buffer [kg/timestep]

Return type:

dict

inputs: Dict = {'buffer_available_h2': 0, 'buffer_free_capacity': 0, 'demand1': 0, 'demand2': 0, 'thermolyzer_out': 0}

outputs: Dict = {'dump': 0}

parameters: Dict = {'dummy': 0}

states: Dict = {'buffer_in': 0, 'desired_out': 0, 'valve1_ratio1': 0, 'valve1_ratio2': 0, 'valve1_ratio3': 0}

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

Advances the simulation one time step.

Parameters:

• time (int) – Current simulation time.

• inputs (dict, optional) – Dictionary containing input values: - demand1 (float): Demand for hydrogen from unit 1 [kg/timestep] - demand2 (float): Demand for hydrogen from unit 2 [kg/timestep] - thermolyzer_out (float): Hydrogen output from the thermolyzer [kg/timestep] - compressor_out (float): Hydrogen output from the compressor [kg/timestep] - h2_soc1 (float): Hydrogen storage 1 state of charge [%] - h2_soc2 (float): Hydrogen storage 2 state of charge [%]

• max_advance (int, optional) – Maximum time to advance. Defaults to 900.

Returns:

Next simulation time.

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.H2controller.H2_controller_example.H2ControllerExample(**kwargs)

A class to represent a Controller model for a hybrid renewable energy system. This class provides methods to manage flows in and out of a buffer.

Attributes parameters : dict

Dictionary containing control parameters like battery and hydrogen storage limits, and fuel cell efficiency.

inputsdict

Dictionary containing inputs like wind/solar generation, load demand, and storage states.

outputsdict

Dictionary containing calculated outputs like power flows to battery/electrolyzer and hydrogen production.

statesdict

Dictionary containing the state variables of the system.

time_step_sizeint

Time step size for the simulation.

timeint or None

Current simulation time.

Methods __init__(**kwargs)

Initializes the Controller model with the provided parameters.

step(time, inputs, max_advance)

Simulates one time step of the H2Controller2 model.

control(demand, demandt, h2_out, h2_soc1, h2_soc2)

Manages hydrogen flows based on generation, demand and storage.

control(demand: float, h2_out: float, buffer_available_h2: float, buffer_free_capacity: float) → dict

This function executes the control operation. Based on how full the hydrogen buffer is and the combination of demand and production, it controls the buffer.

Parameters:

• demand (float) – Demand [kg/timestep]

• hydrogen_out (float) – Production of the hydrogen [kg/timestep]

• buffer_available_h2 (float) – Amount of hydrogen that can be discharged from the buffer [kg]

• buffer_free_capacity (float) – Amount of hydrogen that can be charged before reaching full soc [kg]

Returns:

results – Dictionary containing parameters: - dump: over hydrogen in the system [kg/timestep]

• buffer_in: hydrogen that appears at the input of the buffer [kg/timestep]

• desired_out: amount of hydrogen demanded at the output of the buffer [kg/timestep]

Return type:

dict

inputs: Dict = {'buffer_available_h2': 0, 'buffer_free_capacity': 0, 'demand': 0, 'h2_out': 0}

outputs: Dict = {'dump': 0}

parameters: Dict = {'dummy': 0}

states: Dict = {'buffer_in': 0, 'desired_out': 0}

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

Advances the simulation one time step.

Parameters:

• time (int) – Current simulation time.

• inputs (dict, optional) – Dictionary containing input values: - demand (float): Demand for hydrogen from unit 1 [kg/timestep] - h2_out (float): Hydrogen output from the h2 [kg/timestep] - h2_soc1 (float): Hydrogen storage 1 state of charge [%]

• max_advance (int, optional) – Maximum time to advance. Defaults to 900.

Returns:

Next simulation time.

Return type:

int

time = None

time_step_size: int = 1

class illuminator.models.H2PSA.PSA_v3.H2PSA(**kwargs)

A Pressure Swing Adsorption (PSA) model for hydrogen purification.

This model simulates the operation of a hydrogen PSA unit, applying a specified efficiency to the incoming hydrogen stream to determine the purified hydrogen output.

Parameters:

efficiency (float) – Efficiency of the PSA unit as a percentage [%].

Inputs:

h2_in (float) – Hydrogen flow entering the PSA [kg/timestep].

Outputs:

h2_out (float) – Purified hydrogen flow leaving the PSA [kg/timestep].

States:

(none)

inputs: Dict = {'h2_in': 0}

outputs: Dict = {'h2_out': 0}

parameters: Dict = {'efficiency': 100}

states: Dict = {}

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

Advance the H2 PSA model by one simulation time step.

Processes the input hydrogen flow for the current timestep, applies the PSA efficiency, updates the output flow, and sets the model outputs.

Parameters:

• time (int) – Current simulation time.

• inputs (dict, optional) – Dictionary containing input values: - h2_in (float): Hydrogen flow entering the PSA [kg/timestep].

• max_advance (int, optional) – Maximum time step size (default is 900).

Returns:

Next simulation time step.

Return type:

int

time = None

time_step_size: int = 1