Units Overview

This document provides an overview of the various units available within the ASSUME framework, detailing their respective submodules.

Submodules

Demand Module

The assume.units.demand module contains classes and functions for modeling demand in energy systems.

class assume.units.demand.Demand(id: str, unit_operator: str, technology: str, bidding_strategies: dict, max_power: float, min_power: float, forecaster: Forecaster, node: str = 'node0', price: float = 3000.0, location: tuple[float, float] = (0.0, 0.0), **kwargs)

Bases: SupportsMinMax

A demand unit.

id

The unique identifier of the unit.

Type:

str

unit_operator

The operator of the unit.

Type:

str

technology

The technology of the unit.

Type:

str

bidding_strategies

The bidding strategies of the unit.

Type:

dict

index

The index of the unit.

Type:

pandas.DatetimeIndex

max_power

The maximum power output capacity of the power plant in MW.

Type:

float

min_power

The minimum power output capacity of the power plant in MW. Defaults to 0.0 MW.

Type:

float, optional

node

The node of the unit. Defaults to “node0”.

Type:

str, optional

price

The price of the unit.

Type:

float

location

The location of the unit. Defaults to (0.0, 0.0).

Type:

tuple[float, float], optional

as_dict() → dict

Returns the unit as a dictionary.

Returns:

The unit as a dictionary.

Return type:

dict

calculate_marginal_cost(start: datetime, power: float) → float

Calculate the marginal cost of the unit returns the marginal cost of the unit based on the provided time and power.

Parameters:

• start (pandas.Timestamp) – The start time of the dispatch.

• power (float) – The power output of the unit.

Returns:

the marginal cost of the unit for the given power.

Return type:

float

calculate_min_max_power(start: datetime, end: datetime, product_type='energy') → tuple[numpy.array, numpy.array]

Calculates the minimum and maximum power output of the unit and returns the bid volume as both the minimum and maximum power output of the unit.

Parameters:

• start (pandas.Timestamp) – The start time of the dispatch.

• end (pandas.Timestamp) – The end time of the dispatch.

Returns:

The bid colume as both the minimum and maximum power output of the unit.

Return type:

tuple[pandas.Series, pandas.Series]

execute_current_dispatch(start: datetime, end: datetime) → array

Execute the current dispatch of the unit. Returns the volume of the unit within the given time range.

Parameters:

• start (datetime.datetime) – The start time of the dispatch.

• end (datetime.datetime) – The end time of the dispatch.

Returns:

The volume of the unit for the given time range.

Return type:

np.array

Power Plant Module

The assume.units.powerplant module includes definitions for different types of power plants and their operational characteristics.

class assume.units.powerplant.PowerPlant(id: str, unit_operator: str, technology: str, bidding_strategies: dict, forecaster: Forecaster, max_power: float, min_power: float = 0.0, efficiency: float = 1.0, additional_cost: float = 0.0, partial_load_eff: bool = False, fuel_type: str = 'others', emission_factor: float = 0.0, ramp_up: float | None = None, ramp_down: float | None = None, hot_start_cost: float = 0, warm_start_cost: float = 0, cold_start_cost: float = 0, min_operating_time: float = 0, min_down_time: float = 0, downtime_hot_start: int = 0, downtime_warm_start: int = 0, heat_extraction: bool = False, max_heat_extraction: float = 0, location: tuple[float, float] = (0.0, 0.0), node: str = 'node0', **kwargs)

Bases: SupportsMinMax

A class for a power plant unit.

Parameters:

• id (str) – The ID of the storage unit.

• unit_operator (str) – The operator of the unit.

• technology (str) – The technology of the unit.

• bidding_strategies (dict) – The bidding strategies of the unit.

• index (pandas.DatetimeIndex) – The index of the unit.

• max_power (float) – The maximum power output capacity of the power plant in MW.

• min_power (float, optional) – The minimum power output capacity of the power plant in MW. Defaults to 0.0 MW.

• efficiency (float, optional) – The efficiency of the power plant in converting fuel to electricity. Defaults to 1.0.

• additional_cost (float, optional) – Additional costs associated with power generation, in EUR/MWh. Defaults to 0.

• partial_load_eff (bool, optional) – Does the efficiency vary at part loads? Defaults to False.

• fuel_type (str, optional) – The type of fuel used by the power plant for power generation. Defaults to “others”.

• emission_factor (float, optional) – The emission factor associated with the power plant’s fuel type (CO2 emissions per unit of energy produced). Defaults to 0.0.

• ramp_up (Union[float, None], optional) – The ramp-up rate of the power plant, indicating how quickly it can increase power output. Defaults to None.

• ramp_down (Union[float, None], optional) – The ramp-down rate of the power plant, indicating how quickly it can decrease power output. Defaults to None.

• hot_start_cost (float, optional) – The cost of a hot start, where the power plant is restarted after a recent shutdown. Defaults to 0.

• warm_start_cost (float, optional) – The cost of a warm start, where the power plant is restarted after a moderate downtime. Defaults to 0.

• cold_start_cost (float, optional) – The cost of a cold start, where the power plant is restarted after a prolonged downtime. Defaults to 0.

• min_operating_time (float, optional) – The minimum duration that the power plant must operate once started, in hours. Defaults to 0.

• min_down_time (float, optional) – The minimum downtime required after a shutdown before the power plant can be restarted, in hours. Defaults to 0.

• downtime_hot_start (int, optional) – The downtime required after a hot start before the power plant can be restarted, in hours. Defaults to 8.

• downtime_warm_start (int, optional) – The downtime required after a warm start before the power plant can be restarted, in hours. Defaults to 48.

• heat_extraction (bool, optional) – A boolean indicating whether the power plant can extract heat for external purposes. Defaults to False.

• max_heat_extraction (float, optional) – The maximum amount of heat that the power plant can extract for external use, in some suitable unit. Defaults to 0.

• location (Tuple[float, float], optional) – The geographical coordinates (latitude and longitude) of the power plant’s location. Defaults to (0.0, 0.0).

• node (str, optional) – The identifier of the electrical bus or network node to which the power plant is connected. Defaults to “node0”.

• **kwargs (dict, optional) – Additional keyword arguments to be passed to the base class. Defaults to {}.

as_dict() → dict

Returns the attributes of the unit as a dictionary, including specific attributes.

Returns:

The attributes of the unit as a dictionary.

Return type:

dict

calc_marginal_cost_with_partial_eff(power_output: float, timestep: datetime) → float

Calculates the marginal cost of the unit based on power output and timestamp, considering partial efficiency. Returns the marginal cost of the unit.

Parameters:

• power_output (float) – The power output of the unit.

• timestep (datetime.datetime) – The timestamp of the unit.

Returns:

The marginal cost of the unit at the given timestamp.

Return type:

float

calc_simple_marginal_cost()

Calculates the marginal cost of the unit (simple method) and returns the marginal cost of the unit.

Returns:

The marginal cost of the unit.

Return type:

float

calculate_marginal_cost(start: datetime, power: float)

Calculates the marginal cost of the unit based on the provided start time and power output and returns it. Returns the marginal cost of the unit.

Parameters:

• start (datetime.datetime) – The start time of the dispatch.

• power (float) – The power output of the unit.

Returns:

The marginal cost of the unit.

Return type:

float

calculate_min_max_power(start: datetime, end: datetime, product_type='energy') → tuple[numpy.array, numpy.array]

Calculates the minimum and maximum power output of the unit and returns it.

Parameters:

• start (pandas.Timestamp) – The start time of the dispatch.

• end (pandas.Timestamp) – The end time of the dispatch.

• product_type (str, optional) – The product type of the unit. Defaults to “energy”.

Returns:

The minimum and maximum power output of the unit.

Return type:

tuple[pandas.Series, pandas.Series]

Note

The calculation does not include ramping constraints and can be used for arbitrary start times in the future.

execute_current_dispatch(start: datetime, end: datetime) → array

Executes the current dispatch of the unit based on the provided timestamps.

The dispatch is only executed, if it is in the constraints given by the unit. Returns the volume of the unit within the given time range.

Parameters:

• start (pandas.Timestamp) – The start time of the dispatch.

• end (pandas.Timestamp) – The end time of the dispatch.

Returns:

The volume of the unit within the given time range.

Return type:

np.array

init_marginal_cost()

Initializes the marginal cost of the unit using calc_cimple_marginal_cost().

Args:

Storage Module

The assume.units.storage module provides classes for various energy storage solutions, including batteries and other storage technologies.

class assume.units.storage.Storage(id: str, unit_operator: str, technology: str, bidding_strategies: dict, forecaster: Forecaster, max_power_charge: float, max_power_discharge: float, max_soc: float, min_power_charge: float = 0.0, min_power_discharge: float = 0.0, min_soc: float = 0.0, initial_soc: float = 0.0, soc_tick: float = 0.01, efficiency_charge: float = 1, efficiency_discharge: float = 1, additional_cost_charge: float = 0.0, additional_cost_discharge: float = 0.0, ramp_up_charge: float = None, ramp_down_charge: float = None, ramp_up_discharge: float = None, ramp_down_discharge: float = None, hot_start_cost: float = 0, warm_start_cost: float = 0, cold_start_cost: float = 0, min_operating_time: float = 0, min_down_time: float = 0, downtime_hot_start: int = 8, downtime_warm_start: int = 48, location: tuple[float, float] = (0, 0), node: str = 'node0', **kwargs)

Bases: SupportsMinMaxCharge

A class for a storage unit.

Parameters:

• id (str) – The ID of the storage unit.

• technology (str) – The technology of the storage unit.

• node (str) – The node of the storage unit.

• max_power_charge (float) – The maximum power input of the storage unit in MW (negative value).

• min_power_charge (float) – The minimum power input of the storage unit in MW (negative value).

• max_power_discharge (float) – The maximum power output of the storage unit in MW.

• min_power_discharge (float) – The minimum power output of the storage unit in MW.

• max_soc (float) – The maximum state of charge of the storage unit in MWh (equivalent to capacity).

• min_soc (float) – The minimum state of charge of the storage unit in MWh.

• initial_soc (float) – The initial state of charge of the storage unit in MWh.

• efficiency_charge (float) – The efficiency of the storage unit while charging.

• efficiency_discharge (float) – The efficiency of the storage unit while discharging.

• additional_cost_charge (float, optional) – Additional costs associated with power consumption, in EUR/MWh. Defaults to 0.

• additional_cost_discharge (float, optional) – Additional costs associated with power generation, in EUR/MWh. Defaults to 0.

• ramp_up_charge (float) – The ramp up rate of charging the storage unit in MW/15 minutes (negative value).

• ramp_down_charge (float) – The ramp down rate of charging the storage unit in MW/15 minutes (negative value).

• ramp_up_discharge (float) – The ramp up rate of discharging the storage unit in MW/15 minutes.

• ramp_down_discharge (float) – The ramp down rate of discharging the storage unit in MW/15 minutes.

• hot_start_cost (float) – The hot start cost of the storage unit in €/MW.

• warm_start_cost (float) – The warm start cost of the storage unit in €/MW.

• cold_start_cost (float) – The cold start cost of the storage unit in €/MW.

• downtime_hot_start (float) – Definition of downtime before hot start in h.

• downtime_warm_start (float) – Definition of downtime before warm start in h.

• min_operating_time (float) – The minimum operating time of the storage unit in hours.

• min_down_time (float) – The minimum down time of the storage unit in hours.

• is_active (bool) – Defines whether or not the unit bids itself or is portfolio optimized.

• bidding_startegy (str) – In case the unit is active it has to be defined which bidding strategy should be used

as_dict() → dict

Return the storage unit’s attributes as a dictionary, including specific attributes.

Returns:

The storage unit’s attributes as a dictionary.

Return type:

dict

calculate_marginal_cost(start: datetime, power: float) → float

Calculates the marginal cost of the unit based on the provided start time and power output and returns it. Returns the marginal cost of the unit.

Parameters:

• start (datetime.datetime) – The start time of the dispatch.

• power (float) – The power output of the unit.

Returns:

The marginal cost of the unit.

Return type:

float

calculate_min_max_charge(start: datetime, end: datetime, product_type='energy') → tuple[numpy.array, numpy.array]

Calculates the min and max charging power for the given time period. This is relative to the already sold output on other markets for the same period. It also adheres to reserved positive and negative capacities.

Parameters:

• start (datetime.datetime) – The start of the current dispatch.

• end (datetime.datetime) – The end of the current dispatch.

• product_type (str) – The product type of the storage unit.

Returns:

The minimum and maximum charge power levels of the storage unit in MW.

Return type:

tuple[np.array, np.array]

calculate_min_max_discharge(start: datetime, end: datetime, product_type='energy') → tuple[numpy.array, numpy.array]

Calculates the min and max discharging power for the given time period. This is relative to the already sold output on other markets for the same period. It also adheres to reserved positive and negative capacities.

Parameters:

• start (datetime.datetime) – The start of the current dispatch.

• end (datetime.datetime) – The end of the current dispatch.

• product_type (str) – The product type of the storage unit.

Returns:

The minimum and maximum discharge power levels of the storage unit in MW.

Return type:

tuple[np.array, np.array]

calculate_ramp_charge(soc: float, previous_power: float, power_charge: float, current_power: float = 0, min_power_charge: float = 0) → float

Adjusts the charging power to the ramping constraints.

Parameters:

• soc (float) – The current state of charge.

• previous_power (float) – The previous power output of the unit.

• power_charge (float) – The charging power output of the unit.

• current_power (float, optional) – The current power output of the unit. Defaults to 0.

• min_power_charge (float, optional) – The minimum charging power output of the unit. Defaults to 0.

Returns:

The charging power adjusted to the ramping constraints.

Return type:

float

calculate_ramp_discharge(soc: float, previous_power: float, power_discharge: float, current_power: float = 0, min_power_discharge: float = 0) → float

Adjusts the discharging power to the ramping constraints.

Parameters:

• soc (float) – The current state of charge.

• previous_power (float) – The previous power output of the unit.

• power_discharge (float) – The discharging power output of the unit.

• current_power (float, optional) – The current power output of the unit. Defaults to 0.

• min_power_discharge (float, optional) – The minimum discharging power output of the unit. Defaults to 0.

Returns:

The discharging power adjusted to the ramping constraints.

Return type:

float

calculate_soc_max_charge(soc) → float

Calculates the maximum charge power depending on the current state of charge.

Parameters:

soc (float) – The current state of charge.

Returns:

The maximum charge power.

Return type:

float

calculate_soc_max_discharge(soc) → float

Calculates the maximum discharge power depending on the current state of charge.

Parameters:

soc (float) – The current state of charge.

Returns:

The maximum discharge power.

Return type:

float

execute_current_dispatch(start: datetime, end: datetime) → array

Executes the current dispatch of the unit based on the provided timestamps.

The dispatch is only executed, if it is in the constraints given by the unit. Returns the volume of the unit within the given time range.

Parameters:

• start (datetime.datetime) – The start time of the dispatch.

• end (datetime.datetime) – The end time of the dispatch.

Returns:

The volume of the unit within the given time range.

Return type:

np.array

get_starting_costs(op_time)

Calculates the starting costs of the unit depending on how long it was shut down

Parameters:

op_time (float) – The time the unit was shut down in hours.

Returns:

The starting costs of the unit.

Return type:

float

Demand Side Technology Components Module

The assume.units.dst_components module focuses on components used in Demand Side Technology systems, such as generators and converters.

The following classes are defined within the assume.units.dst_components module:

Electrolyser

A class representing an electrolyser component for hydrogen production.

class assume.units.dst_components.Electrolyser(max_power: float, efficiency: float, time_steps: list[int], min_power: float = 0.0, ramp_up: float | None = None, ramp_down: float | None = None, min_operating_steps: int = 1, min_down_steps: int = 1, initial_operational_status: int = 1, **kwargs)

A class to represent an electrolyser unit used for hydrogen production through electrolysis.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of an electrolyser, including power input, hydrogen output, ramp rates, and operating times.

Parameters:

• max_power (float) – The rated power capacity of the electrolyser.

• efficiency (float) – The efficiency of the electrolysis process (0-1).

• time_steps (list[int]) – A list of time steps over which the electrolyser operates.

• min_power (float) – The minimum power required for operation.

• ramp_up (float, optional) – The maximum rate at which the electrolyser can increase its power output. Defaults to max_power.

• ramp_down (float, optional) – The maximum rate at which the electrolyser can decrease its power output. Defaults to max_power.

• min_operating_steps (int, optional) – The minimum number of steps the electrolyser must operate continuously. Defaults to 1.

• min_down_steps (int, optional) – The minimum number of downtime steps required between operating cycles. Defaults to 1.

• initial_operational_status (int, optional) – The initial operational status of the electrolyser (0 for off, 1 for on). Defaults to 1.

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds an electrolyser block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • max_power: Maximum allowable power input.

  • efficiency: Efficiency of the electrolyser.

  • min_power: Minimum allowable power input.

  • ramp_up: Maximum ramp-up rate.

  • ramp_down: Maximum ramp-down rate.

  • min_operating_steps: Minimum operating time.

  • min_down_steps: Minimum downtime between operating cycles.

  • initial_operational_status: Initial operational status of the electrolyser.

• Variables:

  • power_in[t]: Power input to the electrolyser at each time step t.

  • hydrogen_out[t]: Hydrogen output at each time step t.

  • operating_cost[t]: Operating cost at each time step t.

  • operational_status[t] (optional): Binary variable indicating whether the electrolyser is operational.

  • start_up[t] (optional): Binary variable indicating whether the electrolyser has started up at time t.

  • shut_down[t] (optional): Binary variable indicating whether the electrolyser has shut down at time t.

• Constraints:

  • min_power_constraint[t]: Ensures that the power input is at least the minimum power input when the electrolyser is operational.

  • max_power_constraint[t]: Ensures that the power input does not exceed the maximum power input.

  • hydrogen_production_constraint[t]: Relates power input to hydrogen output based on efficiency.

  • ramp_up_constraint[t]: Limits the ramp-up rate of power input.

  • ramp_down_constraint[t]: Limits the ramp-down rate of power input.

  • min_operating_time_constraint[t]: Ensures the electrolyser operates for a minimum duration.

  • min_downtime_constraint[t]: Ensures the electrolyser remains off for a minimum duration between operations.

  • operating_cost_constraint[t]: Calculates the operating cost based on power input and electricity price.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the electrolyser block will be added.

Returns:

A Pyomo block representing the electrolyser with variables and constraints.

Return type:

pyo.Block

Hydrogen Storage

A class representing a hydrogen storage unit.

Direct Reduced Iron Plant

A class representing a Direct Reduced Iron (DRI) plant.

class assume.units.dst_components.DRIPlant(specific_hydrogen_consumption: float, specific_natural_gas_consumption: float, specific_electricity_consumption: float, specific_iron_ore_consumption: float, max_power: float, min_power: float, fuel_type: str, time_steps: list[int], ramp_up: float | None = None, ramp_down: float | None = None, min_operating_steps: int = 0, min_down_steps: int = 0, initial_operational_status: int = 1, natural_gas_co2_factor: float = 0.5, **kwargs)

A class to represent a DRI (Direct Reduced Iron) plant in an energy system model.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of a DRI plant, including power consumption, fuel consumption (hydrogen, natural gas, or both), iron ore input, and ramp rates.

Parameters:

• specific_hydrogen_consumption (float) – The specific hydrogen consumption of the DRI plant (in MWh per ton of DRI).

• specific_natural_gas_consumption (float) – The specific natural gas consumption of the DRI plant (in MWh per ton of DRI).

• specific_electricity_consumption (float) – The specific electricity consumption of the DRI plant (in MWh per ton of DRI).

• specific_iron_ore_consumption (float) – The specific iron ore consumption of the DRI plant (in ton per ton of DRI).

• max_power (float) – The rated power capacity of the DRI plant.

• min_power (float) – The minimum power required for operation.

• fuel_type (str) – The type of fuel used by the DRI plant (“hydrogen”, “natural_gas”, “both”).

• time_steps (list[int]) – A list of time steps over which the DRI plant operates.

• ramp_up (float, optional) – The maximum rate at which the DRI plant can increase its power output.

• ramp_down (float, optional) – The maximum rate at which the DRI plant can decrease its power output.

• min_operating_steps (int, optional) – The minimum number of steps the DRI plant must operate continuously. Defaults to 0.

• min_down_steps (int, optional) – The minimum number of downtime steps required between operating cycles. Defaults to 0.

• initial_operational_status (int, optional) – The initial operational status of the DRI plant (0 for off, 1 for on). Defaults to 1.

• natural_gas_co2_factor (float, optional) – The CO2 emission factor for natural gas (in ton/MWh). Defaults to 0.5.

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds a DRI plant block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • specific_hydrogen_consumption: Hydrogen consumption per ton of DRI.

  • specific_natural_gas_consumption: Natural gas consumption per ton of DRI.

  • specific_electricity_consumption: Electricity consumption per ton of DRI.

  • specific_iron_ore_consumption: Iron ore consumption per ton of DRI.

  • max_power: Maximum allowable power input.

  • min_power: Minimum allowable power input.

  • ramp_up: Maximum ramp-up rate.

  • ramp_down: Maximum ramp-down rate.

  • min_operating_steps: Minimum operating time.

  • min_down_steps: Minimum downtime between operating cycles.

  • initial_operational_status: Initial operational status of the DRI plant.

  • natural_gas_co2_factor: CO2 emission factor for natural gas.

• Variables:

  • power_in[t]: Power input to the DRI plant at each time step t.

  • dri_output[t]: DRI output at each time step t.

  • natural_gas_in[t]: Natural gas input at each time step t.

  • hydrogen_in[t]: Hydrogen input at each time step t.

  • iron_ore_in[t]: Iron ore input at each time step t.

  • operating_cost[t]: Operating cost at each time step t.

  • operational_status[t] (optional): Binary variable indicating whether the DRI plant is operational.

  • start_up[t] (optional): Binary variable indicating whether the DRI plant has started up at time t.

  • shut_down[t] (optional): Binary variable indicating whether the DRI plant has shut down at time t.

• Constraints:

  • min_power_constraint[t]: Ensures that the power input is at least the minimum power input when the DRI plant is operational.

  • max_power_constraint[t]: Ensures that the power input does not exceed the maximum power input.

  • dri_output_constraint[t]: Links DRI output to fuel (hydrogen or natural gas) consumption.

  • electricity_consumption_constraint[t]: Ensures that electricity consumption is proportional to DRI output.

  • iron_ore_constraint[t]: Links iron ore input to DRI output.

  • ramp_up_constraint[t]: Limits the ramp-up rate of power input.

  • ramp_down_constraint[t]: Limits the ramp-down rate of power input.

  • min_operating_time_constraint[t]: Ensures the DRI plant operates for a minimum duration.

  • min_downtime_constraint[t]: Ensures the DRI plant remains off for a minimum duration between operations.

  • operating_cost_constraint[t]: Calculates the operating cost based on fuel and electricity consumption.

  • co2_emission_constraint[t]: Calculates the CO2 emissions based on natural gas consumption.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the DRI plant component will be added.

Returns:

A Pyomo block representing the DRI plant with variables and constraints.

Return type:

pyo.Block

Direct Reduced Iron Storage

A class representing DRI storage solutions.

class assume.units.dst_components.DRIStorage(max_capacity: float, time_steps: list[int], min_capacity: float = 0.0, max_power_charge: float | None = None, max_power_discharge: float | None = None, efficiency_charge: float = 1.0, efficiency_discharge: float = 1.0, initial_soc: float = 1.0, ramp_up: float | None = None, ramp_down: float | None = None, storage_loss_rate: float = 0.0, **kwargs)

A class to represent a Direct Reduced Iron (DRI) storage unit in an energy system model.

Inherits all the functionality from GenericStorage and can be extended in the future with DRI-specific constraints or attributes.

Parameters:

class. (Inherits all attributes from the GenericStorage) –

add_to_model(model: ConcreteModel, model_block: Block) → Block

Creates and returns a Pyomo Block for the DRI storage component. This method can be extended in the future with DRI-specific constraints or variables.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the DRI storage component will be added.

Returns:

A Pyomo block representing the DRI storage with variables and constraints.

Return type:

pyo.Block

Electric Arc Furnace

A class representing an electric arc furnace component.

class assume.units.dst_components.ElectricArcFurnace(max_power: float, min_power: float, specific_electricity_consumption: float, specific_dri_demand: float, specific_lime_demand: float, lime_co2_factor: float, time_steps: list[int], ramp_up: float | None = None, ramp_down: float | None = None, min_operating_steps: int = 0, min_down_steps: int = 0, initial_operational_status: int = 1, **kwargs)

A class to represent an Electric Arc Furnace (EAF) in an energy system model.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of an EAF, including power consumption, DRI input, lime demand, and ramp rates.

Parameters:

• max_power (float) – The rated power capacity of the electric arc furnace.

• min_power (float) – The minimum power requirement of the electric arc furnace.

• specific_electricity_consumption (float) – The specific electricity consumption of the electric arc furnace (in MWh per ton of steel produced).

• specific_dri_demand (float) – The specific demand for Direct Reduced Iron (DRI) in the electric arc furnace (in tons per ton of steel produced).

• specific_lime_demand (float) – The specific demand for lime in the electric arc furnace (in tons per ton of steel produced).

• lime_co2_factor (float) – The CO2 emission factor for lime production (in ton/MWh).

• time_steps (list[int]) – A list of time steps over which the EAF operates.

• ramp_up (float, optional) – The ramp-up rate of the electric arc furnace. Defaults to max_power.

• ramp_down (float, optional) – The ramp-down rate of the electric arc furnace. Defaults to max_power.

• min_operating_steps (int, optional) – The minimum number of steps the EAF must operate continuously. Defaults to 0.

• min_down_steps (int, optional) – The minimum number of downtime steps required between operating cycles. Defaults to 0.

• initial_operational_status (int, optional) – The initial operational status of the EAF (0 for off, 1 for on). Defaults to 1.

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds an EAF block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • max_power: Maximum allowable power input.

  • min_power: Minimum allowable power input.

  • specific_electricity_consumption: Electricity consumption per ton of steel produced.

  • specific_dri_demand: DRI demand per ton of steel produced.

  • specific_lime_demand: Lime demand per ton of steel produced.

  • lime_co2_factor: CO2 emission factor for lime production.

  • ramp_up: Maximum ramp-up rate.

  • ramp_down: Maximum ramp-down rate.

  • min_operating_steps: Minimum operating time.

  • min_down_steps: Minimum downtime between operating cycles.

  • initial_operational_status: Initial operational status of the EAF.

• Variables:

  • power_in[t]: Power input to the EAF at each time step t.

  • dri_input[t]: DRI input at each time step t.

  • steel_output[t]: Steel output at each time step t.

  • operating_cost[t]: Operating cost at each time step t.

  • co2_emission[t]: CO2 Emissions at each time step t.

  • lime_demand[t]: Lime demand at each time step t.

  • operational_status[t] (optional): Binary variable indicating whether the EAF is operational.

  • start_up[t] (optional): Binary variable indicating whether the EAF has started up at time t.

  • shut_down[t] (optional): Binary variable indicating whether the EAF has shut down at time t.

• Constraints:

  • min_power_constraint[t]: Ensures that the power input is at least the minimum power input when the EAF is operational.

  • max_power_constraint[t]: Ensures that the power input does not exceed the maximum power input.

  • steel_output_dri_relation_constraint[t]: Links steel output to DRI input.

  • steel_output_power_relation_constraint[t]: Links steel output to power consumption.

  • lime_demand_constraint[t]: Links lime demand to steel output.

  • co2_emission_constraint[t]: Links CO2 emissions to lime demand.

  • ramp_up_constraint[t]: Limits the ramp-up rate of power input.

  • ramp_down_constraint[t]: Limits the ramp-down rate of power input.

  • min_operating_time_constraint[t]: Ensures the EAF operates for a minimum duration.

  • min_down_time_constraint[t]: Ensures the EAF remains off for a minimum duration between operations.

  • operating_cost_constraint[t]: Calculates the operating cost based on power input, CO2 emissions, and lime consumption.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the EAF component will be added.

Returns:

A Pyomo block representing the EAF with variables and constraints.

Return type:

pyo.Block

Heat Pump

A class representing a heat pump component in energy systems.

class assume.units.dst_components.HeatPump(max_power: float, cop: float, time_steps: list[int], min_power: float = 0.0, ramp_up: float | None = None, ramp_down: float | None = None, min_operating_steps: int = 0, min_down_steps: int = 0, initial_operational_status: int = 1, **kwargs)

A class to represent a generic heat pump unit in an energy system model.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of a heat pump, such as power input, heat output, and operational limitations (like ramp rates and minimum operating times).

Parameters:

• max_power (float) – Maximum allowable power input to the heat pump.

• cop (float) – Coefficient of performance of the heat pump, i.e., the ratio of heat output to power input.

• time_steps (list[int]) – A list of time steps over which the heat pump operates.

• min_power (float, optional) – Minimum allowable power input to the heat pump. Defaults to 0.0.

• ramp_up (float, optional) – Maximum allowed increase in power input per time step. Defaults to max_power if not provided.

• ramp_down (float, optional) – Maximum allowed decrease in power input per time step. Defaults to max_power if not provided.

• min_operating_steps (int, optional) – Minimum number of consecutive time steps the heat pump must operate once it starts. Defaults to 0 (no restriction).

• min_down_steps (int, optional) – Minimum number of consecutive time steps the heat pump must remain off after being shut down. Defaults to 0 (no restriction).

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds a heat pump block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • max_power: The maximum allowable power input.

  • min_power: The minimum allowable power input.

  • cop: Coefficient of performance of the heat pump.

  • operating_cost: Operating cost at each time step per time step.

  • ramp_up: Maximum allowed increase in power per time step.

  • ramp_down: Maximum allowed decrease in power per time step.

  • min_operating_steps: Minimum number of consecutive time steps the heat pump must operate.

  • min_down_steps: Minimum number of consecutive time steps the heat pump must remain off.

  • initial_operational_status: The initial operational status of the heat pump (0 for off, 1 for on).

• Variables:

  • power_in[t]: Power input to the heat pump at each time step t (continuous, non-negative).

  • heat_out[t]: Heat output of the heat pump at each time step t (continuous, non-negative).

  • operational_status[t] (optional): A binary variable indicating whether the heat pump is operational (1) or off (0) at each time step t.

  • start_up[t] (optional): A binary variable indicating whether the heat pump is starting up (1) or not (0) at each time step t.

  • shut_down[t] (optional): A binary variable indicating whether the heat pump is shutting down (1) or not (0) at each time step t.

• Constraints:

  • min_power_constraint[t]: Ensures that the power input is at least the minimum power input when the heat pump is operational.

  • max_power_constraint[t]: Ensures that the power input does not exceed the maximum power input when the heat pump is operational.

  • cop_constraint[t]: Enforces the relationship between power input and heat output based on the coefficient of performance (COP).

  • operating_cost_constraint[t]: Calculates the operating cost based on the power input and electricity price.

  • ramp_up_constraint[t]: Limits the increase in power input from one time step to the next according to the ramp-up rate.

  • ramp_down_constraint[t]: Limits the decrease in power input from one time step to the next according to the ramp-down rate.

  • min_operating_time_constraint[t]: Ensures the heat pump operates for at least the specified minimum number of consecutive time steps.

  • min_downtime_constraint[t]: Ensures the heat pump remains off for at least the specified minimum number of consecutive time steps after shutdown.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the heat pump block will be added.

Returns:

A Pyomo block representing the heat pump with variables and constraints.

Return type:

pyo.Block

Boiler

A class representing a boiler component in energy systems.

class assume.units.dst_components.Boiler(max_power: float, efficiency: float, time_steps: list[int], fuel_type: str = 'electricity', min_power: float = 0.0, ramp_up: float | None = None, ramp_down: float | None = None, min_operating_steps: int = 0, min_down_steps: int = 0, initial_operational_status: int = 1, **kwargs)

A class to represent a generic boiler unit in an energy system model.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of a boiler, which can be either electric or natural gas-based, along with ramp rates and operational limitations.

Parameters:

• max_power (float) – Maximum allowable power input to the boiler.

• efficiency (float) – Efficiency of the boiler, defined as the ratio of heat output to power input (or fuel input).

• time_steps (list[int]) – A list of time steps over which the boiler operates.

• fuel_type (str, optional) – Type of fuel used by the boiler (‘electricity’ or ‘natural_gas’). Defaults to ‘electricity’.

• min_power (float, optional) – Minimum allowable power input to the boiler. Defaults to 0.0.

• ramp_up (float, optional) – Maximum allowed increase in power input per time step. Defaults to max_power if not provided.

• ramp_down (float, optional) – Maximum allowed decrease in power input per time step. Defaults to max_power if not provided.

• min_operating_steps (int, optional) – Minimum number of consecutive time steps the boiler must operate once started. Defaults to 0.

• min_down_steps (int, optional) – Minimum number of consecutive time steps the boiler must remain off after being shut down. Defaults to 0.

• initial_operational_status (int, optional) – The initial operational status of the boiler (0 for off, 1 for on). Defaults to 1.

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds a boiler block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • max_power: The maximum allowable power input.

  • min_power: The minimum allowable power input.

  • efficiency: Efficiency of the boiler.

  • ramp_up: Maximum allowed increase in power per time step.

  • ramp_down: Maximum allowed decrease in power per time step.

  • min_operating_steps: Minimum number of consecutive time steps the boiler must operate.

  • min_down_steps: Minimum number of consecutive time steps the boiler must remain off.

  • initial_operational_status: The initial operational status of the boiler (0 for off, 1 for on).

• Variables:

  • power_in[t] (for electric boilers): Power input at each time step t (continuous, non-negative).

  • natural_gas_in[t] (for natural gas boilers): Natural gas input at each time step t (continuous, non-negative).

  • heat_out[t]: Heat output at each time step t (continuous, non-negative).

  • operational_status[t] (optional, for electric boilers): A binary variable indicating whether the boiler is operational (1) or off (0) at each time step t.

  • start_up[t] (optional, for electric boilers): A binary variable indicating whether the boiler is starting up (1) or not (0) at each time step t.

  • shut_down[t] (optional, for electric boilers): A binary variable indicating whether the boiler is shutting down (1) or not (0) at each time step t.

• Constraints:

  • min_power_constraint[t] (for electric boilers): Ensures that the power input is at least the minimum power input when the boiler is operational.

  • max_power_constraint[t] (for electric boilers): Ensures that the power input does not exceed the maximum power input when the boiler is operational.

  • efficiency_constraint[t]: Enforces the relationship between input (power or natural gas) and heat output based on the boiler’s efficiency.

  • ramp_up_constraint[t]: Limits the increase in power input from one time step to the next according to the ramp-up rate.

  • ramp_down_constraint[t]: Limits the decrease in power input from one time step to the next according to the ramp-down rate.

  • min_operating_time_constraint[t]: Ensures the boiler operates for at least the specified minimum number of consecutive time steps.

  • min_downtime_constraint[t]: Ensures the boiler remains off for at least the specified minimum number of consecutive time steps after shutdown.

  • operating_cost_constraint[t]: Calculates the operating cost based on the power input and electricity price (for electric boilers).

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the boiler block will be added.

Returns:

A Pyomo block representing the boiler with variables and constraints.

Return type:

pyo.Block

Electric Vehicle

A class representing an electric vehicle component.

class assume.units.dst_components.ElectricVehicle(max_capacity: float, time_steps: list[int], availability_profile: Series, max_power_charge: float, min_capacity: float = 0.0, max_power_discharge: float = 0, efficiency_charge: float = 1.0, efficiency_discharge: float = 1.0, initial_soc: float = 1.0, ramp_up: float | None = None, ramp_down: float | None = None, charging_profile: Series | None = None, storage_loss_rate: float = 0.0, **kwargs)

A class to represent an Electric Vehicle (EV) unit in an energy system model.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of an EV, including charging and discharging, battery storage limits, availability profiles, and ramp rates.

Inherits from GenericStorage and adds EV-specific functionality, such as availability profiles and predefined charging profiles.

Parameters:

• max_capacity (float) – Maximum capacity of the EV battery.

• min_capacity (float) – Minimum capacity of the EV battery.

• max_power_charge (float) – Maximum allowable charging power.

• max_power_discharge (float) – Maximum allowable discharging power. Defaults to 0 (no discharging allowed).

• availability_profile (pd.Series) – A pandas Series indicating the EV’s availability, where 1 means available and 0 means unavailable.

• time_steps (list[int]) – A list of time steps over which the EV operates.

• efficiency_charge (float, optional) – Charging efficiency of the EV. Defaults to 1.0.

• efficiency_discharge (float, optional) – Discharging efficiency of the EV. Defaults to 1.0.

• initial_soc (float, optional) – Initial state of charge (SOC) of the EV, represented as a fraction of max_capacity. Defaults to 1.0.

• ramp_up (float, optional) – Maximum allowed increase in charging power per time step. Defaults to None (no ramp constraint).

• ramp_down (float, optional) – Maximum allowed decrease in charging power per time step. Defaults to None (no ramp constraint).

• charging_profile (pd.Series | None, optional) – A predefined charging profile. If provided, the EV follows this profile instead of optimizing the charge. Defaults to None.

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds an EV block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • max_capacity: Maximum battery capacity of the EV.

  • min_capacity: Minimum allowable battery capacity.

  • max_power_charge: Maximum charging power.

  • max_power_discharge: Maximum discharging power.

  • efficiency_charge: Charging efficiency.

  • efficiency_discharge: Discharging efficiency.

• Variables:

  • charge[t]: Charging power input at each time step t.

  • discharge[t]: Discharging power output at each time step t.

  • soc[t]: State of charge (SOC) of the EV battery at each time step t.

• Constraints:

  • availability_constraints: Ensures charging and discharging occur only during available periods.

  • charging_profile_constraints: Enforces predefined charging profiles if provided.

  • soc_constraints: Keeps SOC between min_capacity and max_capacity.

  • ramp_constraints: Limits ramp-up and ramp-down rates for charging.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the EV component will be added.

Returns:

A Pyomo block representing the EV with variables and constraints.

Return type:

pyo.Block

Generic Storage

A class representing a generic storage unit for various applications.

class assume.units.dst_components.GenericStorage(max_capacity: float, time_steps: list[int], min_capacity: float = 0.0, max_power_charge: float | None = None, max_power_discharge: float | None = None, efficiency_charge: float = 1.0, efficiency_discharge: float = 1.0, initial_soc: float = 1.0, ramp_up: float | None = None, ramp_down: float | None = None, storage_loss_rate: float = 0.0, **kwargs)

A class to represent a generic storage unit (e.g., battery) in an energy system model.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of a storage system, including charging, discharging, state of charge (SOC), ramp rates, and storage losses.

Parameters:

• max_capacity (float) – Maximum energy storage capacity of the storage unit.

• min_capacity (float, optional) – Minimum allowable state of charge (SOC). Defaults to 0.0.

• max_power_charge (float, optional) – Maximum charging power of the storage unit. Defaults to max_capacity if not provided.

• max_power_discharge (float, optional) – Maximum discharging power of the storage unit. Defaults to max_capacity if not provided.

• efficiency_charge (float, optional) – Efficiency of the charging process. Defaults to 1.0.

• efficiency_discharge (float, optional) – Efficiency of the discharging process. Defaults to 1.0.

• initial_soc (float, optional) – Initial state of charge as a fraction of max_capacity. Defaults to 1.0.

• ramp_up (float, optional) – Maximum allowed increase in charging/discharging power per time step. Defaults to None (no ramp constraint).

• ramp_down (float, optional) – Maximum allowed decrease in charging/discharging power per time step. Defaults to None (no ramp constraint).

• storage_loss_rate (float, optional) – Fraction of energy lost per time step due to storage inefficiencies. Defaults to 0.0.

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds a generic storage block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • max_capacity: Maximum capacity of the storage unit.

  • min_capacity: Minimum state of charge (SOC).

  • max_power_charge: Maximum charging power.

  • max_power_discharge: Maximum discharging power.

  • efficiency_charge: Charging efficiency.

  • efficiency_discharge: Discharging efficiency.

  • initial_soc: Initial state of charge.

  • ramp_up: Maximum allowed ramp-up rate for charging and discharging.

  • ramp_down: Maximum allowed ramp-down rate for charging and discharging.

  • storage_loss_rate: Fraction of energy lost during storage.

• Variables:

  • soc[t]: State of charge (SOC) at each time step t.

  • charge[t]: Charging power at each time step t.

  • discharge[t]: Discharging power at each time step t.

• Constraints:

  • soc_balance_rule[t]: Tracks SOC changes over time based on charging, discharging, and storage loss.

  • charge_ramp_up_constraint[t]: Limits the ramp-up rate for charging if specified.

  • discharge_ramp_up_constraint[t]: Limits the ramp-up rate for discharging if specified.

  • charge_ramp_down_constraint[t]: Limits the ramp-down rate for charging if specified.

  • discharge_ramp_down_constraint[t]: Limits the ramp-down rate for discharging if specified.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the storage block will be added.

Returns:

A Pyomo block representing the storage system with variables and constraints.

Return type:

pyo.Block

PV Plant

A class representing a photovoltaic (PV) power plant component.

class assume.units.dst_components.PVPlant(max_power: float, time_steps: list[int], availability_profile: Series | None = None, power_profile: Series | None = None, **kwargs)

A class to represent a Photovoltaic (PV) power plant unit in an energy system model.

The class encapsulates the parameters, variables, and constraints necessary to model the behavior of a PV plant, including availability profiles and predefined power output profiles.

Parameters:

• max_power (float) – The maximum power output of the PV unit.

• time_steps (list[int]) – A list of time steps over which the PV operates.

• availability_profile (pd.Series | None, optional) – A pandas Series indicating the PV’s availability with time_steps as indices and binary values (1 available, 0 unavailable). Defaults to None.

• power_profile (pd.Series | None, optional) – A predefined power output profile. If provided, the PV follows this profile instead of optimizing the power output. Defaults to None.

add_to_model(model: ConcreteModel, model_block: Block) → Block

Adds a PV plant block to the Pyomo model, defining parameters, variables, and constraints.

Pyomo Components:

• Parameters:

  • max_power: Maximum allowable power output.

• Variables:

  • power[t]: Power output of the PV plant at each time step t.

  • operating_cost[t]: Operating cost at each time step.

• Constraints:

  • power_profile_constraint: Ensures the PV follows a predefined power profile if provided.

  • availability_pv_constraint: Ensures the PV operates only during available periods.

  • max_power_pv_constraint: Ensures the power output of the PV unit does not exceed the maximum power limit.

  • operating_cost_constraint_rule: Calculates the operating cost based on the power output and electricity price.

Parameters:

• model (pyo.ConcreteModel) – A Pyomo ConcreteModel object representing the optimization model.

• model_block (pyo.Block) – A Pyomo Block object to which the PV plant block will be added.

Returns:

A Pyomo block representing the PV plant with variables and constraints.

Return type:

pyo.Block

Module Contents

The following section provides an overview of the primary contents within the assume.units module, summarizing its main functionalities.