Component

  • File name: component.py

  • Last edited: 2020-06-30

  • Created by: Stefan Bruche (TU Berlin)

Components are added to an instance of the EnergySystem class. The Component class holds basic parameters (e.g., DataFrames for variables and parameters) and methods (e.g., calculate contributions to the objective function), that are required in all types of components. aristopy has five basic component types that are inheriting the parameters and methods from the Component class: Source, Sink, Conversion, Bus, Storage. The Component class itself contains abstract methods and can, therefore, not be instantiated itself.

class aristopy.component.Component(ensys, name, inlet, outlet, basic_variable, has_existence_binary_var=False, has_operation_binary_var=False, time_series_data=None, scalar_params=None, additional_vars=None, user_expressions=None, capacity=None, capacity_min=None, capacity_max=None, capacity_per_module=None, maximal_module_number=None, capex_per_capacity=0, capex_if_exist=0, opex_per_capacity=0, opex_if_exist=0, opex_operation=0)[source]

Initialize an instance of the Component class. Note that an instance of the class Component itself can not be instantiated since it holds abstract methods. The abstract methods are later overwritten by the child classes to enable instantiation.

Parameters

  • ensys (instance of aristopy's EnergySystem class) – EnergySystem instance the component is added to.

  • name (str) – Unique name of the component or the component group.

  • inlet ((list of) instance(s) of aristopy's Flow class, or None) – The inlet holds a set of aristopy’s Flow instances, transporting commodities, entering the component. The commodities are creating variables inside of the component. The variable name is consistent with the name of the commodity, if not specified differently in the Flow instance.
    Example: inlet=aristopy.Flow(‘ABC’, var_name=’XYZ’) => commodity ‘ABC’ is entering the component, and is represented by a newly an internally added variable with the name ‘XYZ’.

  • outlet ((list of) instance(s) of aristopy's Flow class, or None) – See description of keyword argument ‘inlet’.

  • basic_variable (str) – Components may have multiple variables, but every component has only one basic variable. It is used to restrict capacities, set operation rates, and calculate CAPEX and OPEX (if available). Usually, the basic variable points to a commodity variable on the inlet or the outlet of the component. In this case, users need to use string inputs ‘inlet_variable’ or ‘outlet_variable’, respectively. If any other variable should be used as the basic variable (e.g., added via keyword argument ‘additional_vars’), users need to set the variable name directly, as specified during declaration.

  • has_existence_binary_var (bool) – States if the component has a binary variable that indicates its existence status. If the parameter is set to True, a scalar pyomo binary variable is added to the pyomo block model of the component (name specified in utils-file, default: ‘BI_EX’). It can be used to enable minimal component capacities (‘capacity_min’), or capacity-independent CAPEX and OPEX (‘capex_if_exist’, ‘opex_if_exist’).
    Default: False

  • has_operation_binary_var (bool) – States if the component has a binary variable that indicates its operational status. If the parameter is set to True, a pyomo binary variable, utilizing the global EnergySystem time set, is added to the pyomo block model of the component (name specified in utils-file, default: ‘BI_OP’). It can be used to enable load-depending conversion rates (via ‘user_expressions’), or minimal part-loads (‘min_load_rel’), and start-up cost (‘start_up_cost’) (the last two only for Conversion).
    Default: False

  • time_series_data ((list of) instance(s) of aristopy's Series class, or None) – Keyword argument for adding time series data to the component by using instances of aristopy’s Series class. This data can be used for manual scripting in the ‘user_expressions’.
    Default: None

  • scalar_params (dict, or None) – Keyword argument for adding scalar parameters to the component by using a Python dict {‘parameter_name’: value}. The scalar parameters can be used for manual scripting in the ‘user_expressions’.
    Default: None

  • additional_vars ((list of) instance(s) of aristopy's Var class, or None) – Keyword argument for adding variables to the component, that are not automatically created, e.g., by attaching Flows to the inlet or outlet. The variables are provided by adding a set of aristopy’s Var instances.
    Example: additional_vars=aristopy.Var(‘ABC’, domain=’Reals’, ub=42)
    Default: None

  • user_expressions ((list of) str, or None) – Keyword argument for adding expression-like strings, which are converted into pyomo constraints during model declaration. User expressions can be applied for various ends, e.g., for specifying commodity conversion rates, or limiting capacities. The options for mathematical operators are: ‘sum’, ‘sin’, ‘cos’, ‘exp’, ‘log’, ‘==’, ‘>=’, ‘<=’, ‘**’, ‘*’, ‘/’, ‘+’, ‘-‘, ‘(‘, ‘)’. The expressions can handle variables that are created with standard names (see Globals in utils-file, e.g., CAP), and the variables and parameters added by the user via keyword arguments: ‘inlet’, ‘outlet’, ‘time_series_data’, ‘scalar_params’, ‘additional_vars’.
    Example: user_expressions=[‘Q == 0.5*F + 2*BI_OP’, ‘CAP <= 42’]
    Default: None

  • capacity (float or int (>=0), or None) – States the fixed capacity value of the component, if the component exists. Hence, if the parameter ‘has_existence_binary_var’ is set to True, the value for ‘capacity’ is only applied if the component is selected in the optimal design (BI_EX=1).
    Default: None

  • capacity_min (float or int (>=0), or None) – States the minimal component capacity, if the component exists. Hence, if the parameter ‘has_existence_binary_var’ is set to True, the value for ‘capacity_min’ is only applied if the component is selected in the optimal design (BI_EX=1).
    Default: None

  • capacity_max (float or int (>=0), or None) – States the maximal component capacity. This value introduces an upper bound for the capacity variable. It also serves as an over-estimator and is required if the parameters ‘has_existence_binary_var’ or ‘has_operation_binary_var’ is True.
    Default: None

  • capacity_per_module (float or int (>=0), or None) – If a component is modular, its capacity can be modeled with parameter ‘capacity_per_module’. If a value is introduced, an additional binary variable is created (default name: ‘BI_MODULE_EX’), which indicates the existence of each module.
    Default: None

  • maximal_module_number (int (>0), or None) – This keyword argument works in combination with parameter ‘capacity_per_module’ and indicates the maximal number of modules to be installed in the optimal design.
    Default: None

  • capex_per_capacity (float or int (>=0)) – Parameter to calculate the capital investment cost associated with the CAPACITY of a component. The final value for capacity-related CAPEX is obtained by multiplying ‘capex_per_capacity’ with the capacity variable value (CAP).
    Default: 0

  • capex_if_exist (float or int (>=0)) – Parameter to calculate the capital investment cost associated with the EXISTENCE of a component. The final value for existence-related CAPEX is obtained by multiplying ‘capex_if_exist’ with the binary existence variable value (BI_EX).
    Default: 0

  • opex_per_capacity (float or int (>=0)) – Parameter to calculate the annual operational cost associated with the CAPACITY of a component. The final value for capacity-related OPEX is obtained by multiplying ‘opex_per_capacity’ with the capacity variable value (CAP).
    Default: 0

  • opex_if_exist (float or int (>=0)) – Parameter to calculate the annual operational cost associated with the EXISTENCE of a component. The final value for existence-related OPEX is obtained by multiplying ‘opex_if_exist’ with the binary existence variable value (BI_EX).
    Default: 0

  • opex_operation (float or int (>=0)) – Parameter to calculate the annual operational cost associated with the OPERATION of a component (associated with its basic variable). The final value for operation-related OPEX is obtained by summarizing the products of ‘opex_operation’ with the time-dependent values of the basic variable.
    Default: 0

pprint()[source]

Access the pretty print functionality of the pyomo model Block

add_to_energy_system(ensys, group, instances_in_group=1)[source]

Add the component to the specified instance of the EnergySystem class. This implies, creation of copies with unique names if multiple identical components should be instantiated (‘instances_in_group’ > 1), adding the component to the dictionary ‘components’ of the EnergySystem, and initializing a Logger instance for each component.

Method is not intended for public access!

Parameters

  • ensys – EnergySystem instance the component is added to.

  • group – Name (str) of the group where the component is added to (corresponds to initialization keyword attribute ‘name’).

  • instances_in_group – (int > 0) States the number of similar component instances that are simultaneously created and arranged in a group. That means, the user has the possibility to instantiate multiple component instances (only for Conversion!) with identical specifications. These components work independently, but may have an order for their binary existence and/or operation variables (see: ‘group_has_existence_order’, ‘group_has_operation_order’). If a number larger than 1 is provided, the names of the components are extended with integers starting from 1 (e.g., ‘conversion_1’, …).
    Default: 1

add_var(name, domain='NonNegativeReals', has_time_set=True, alternative_set=None, ub=None, lb=None, init=None)[source]

Method for adding a variable to the pandas DataFrame ‘variables’.

Method is not intended for public access!

Parameters

  • name – (str) Name / identifier of the added variable.

  • domain – (str) A super-set of the values the variable can take on. Possible values are: ‘Reals’, ‘NonNegativeReals’, ‘Binary’.
    Default: ‘NonNegativeReals’

  • has_time_set – (bool) Is True, if the time set of the EnergySystem instance is also a set of the added variable.
    * Default: True

  • alternative_set – Alternative variable sets can be added here via iterable Python objects (e.g. list).
    Default: None

  • ub – (float, int, None) Upper variable bound.
    Default: None

  • lb – (float, int, None) Lower variable bound.
    Default: None

  • init – A function or Python object that provides starting values for the added variable.
    Default: None

store_var_copy(name, var)[source]

Method to store the current specifications of a provided variable in the pandas DataFrame “variables_copy”.

Method is not intended for public access!

Parameters

  • name – (str) Name / identifier of the stored variable.

  • var – (pandas Series) Variable data to store.

relax_integrality(include_existence=True, include_modules=True, include_time_dependent=True, store_previous_variables=True)[source]

Method to relax the integrality of the binary variables. This means binary variables are declared to be ‘NonNegativeReals’ with an upper bound of 1. This method encompasses the resetting of the DataFrame “variables” and the pyomo variables itself (if already constructed). The relaxation can be performed for the binary existence variable, the module existence binary variables and time-dependent binary variables.

Parameters

  • include_existence (bool) – State whether the integrality of the binary existence variables should be relaxed (if available).
    Default: True

  • include_modules (bool) – State whether the integrality of the binary modules existence variables should be relaxed (if available).
    Default: True

  • include_time_dependent (bool) – State whether the integrality of the time-dependent binary variables should be relaxed. (if available).
    Default: True

  • store_previous_variables (bool) – State whether the representation of the variables before applying the relaxation should be stored in the DataFrame “variables_copy”. This representation can be used by method “reset_variables” to undo changes.
    Default: True

edit_variable(name, store_previous_variables=True, **kwargs)[source]

Method on component level for manipulating the specifications of already defined component variables (e.g., change variable domain, add variable bounds, etc.).

Parameters

  • name (str) – Name / identifier of the edited variable.

  • store_previous_variables (bool) – State whether the representation of the variables before applying the edit_variable method should be stored in DataFrame “variables_copy” of each component. This representation can be used by mehtod “reset_variables” to undo changes.
    Default: True

  • kwargs – Additional keyword arguments for editing. Options are: ‘ub’ and ‘lb’ to add an upper or lower variable bound, ‘domain’ to set the variable domain, and ‘has_time_set’ to define if the variable should inherit the global time set of the EnergySystem.

reset_variables()[source]

Method to reset the variables to the state, that is stored in the DataFrame “variables_copy”. This includes the resetting of the DataFrame “variables” and the pyomo variables itself (if already constructed).

export_component_configuration()[source]

This method exports the component configuration data (results of the optimization) as a pandas Series. The features are (if exist):

  • the binary existence variable (utils.BI_EX),

  • the binary existence variables of modules (utils.BI_MODULE_EX)

  • the component capacity variable (of main commodity, utils.CAP)

Returns

The configuration of the modelled component instance.

Return type

pandas Series

import_component_configuration(data, fix_existence=True, fix_modules=True, fix_capacity=True, store_previous_variables=True)[source]

Method to load a pandas Series with configuration specifications (binary existence variables and capacity variable values). The values are used to fix a specific component configuration (for example from other model runs).

Parameters

  • data (pandas Series) – The configuration of the modelled component instance.

  • fix_existence (bool) – Specify whether the imported (global) binary component existence variable should be fixed (if available).
    Default: True

  • fix_modules (bool) – Specify whether the imported binary existence variable of the component modules should be fixed (if available).
    Default: True

  • fix_capacity (bool) – Specify whether the imported component capacity variable (of the main commodity) should be fixed or not.
    Default: True

  • store_previous_variables (bool) – State whether the representation of the variables before applying the configuration import should be stored in DataFrame “variables_copy” of each component. This representation can be used by method “reset_variables” to undo changes.
    Default: True

add_param(name, data, tsam_weight=1)[source]

Method for adding a parameter to the pandas DataFrame ‘parameters’.

Method is not intended for public access!

Parameters

  • name – (str) Name / identifier of the added parameter.

  • data – (float, int, list, dict, numpy array, pandas Series) Data.

  • tsam_weight – (int or float) Weighting factor to use in case the provided parameter is a series and an aggregation is requested.
    Default: 1

set_time_series_data(use_clustered_data)[source]

Sets the time series data in the ‘parameters’ DataFrame of a component depending on whether a calculation with aggregated time series data should be performed or with the original data (without clustering).

Method is not intended for public access!

Parameters

use_clustered_data (bool) – Use aggregated data (True), or original data (False).

get_time_series_data_for_aggregation()[source]

Collect all time series data and their respective weights and merge them in two dictionaries. The returned dictionaries are used for the time series aggregation in the “cluster” method of the EnergySystem instance.

Method is not intended for public access!

Returns

(dict) time series data, (dict) time series weights

set_aggregated_time_series_data(data)[source]

Store the aggregated time series data in the ‘parameters’ DataFrame.

Method is not intended for public access!

Parameters

data – (pandas DataFrame) DataFrame with the aggregated time series data of all components.

declare_component_model_block(model)[source]

Create a pyomo Block and store it in attribute ‘block’ of the component. The pyomo Block is the container for all pyomo objects of the component.

Method is not intended for public access!

Parameters

model – Pyomo ConcreteModel of the EnergySystem instance

declare_component_variables(model)[source]

Create all pyomo variables that are stored in DataFrame ‘variables’.

Method is not intended for public access!

Parameters

model – Pyomo ConcreteModel of the EnergySystem instance

declare_component_ports()[source]

Create all ports from the dictionaries ‘inlet_commod_and_var_names’ and ‘outlet_commod_and_var_names’, and assign port variables.

Note: The ports are currently always created with extensive behaviour!

Method is not intended for public access!

declare_component_user_constraints(model)[source]

Create all constraints, that are introduced by manual scripting in the keyword argument ‘user_expressions’.

Method is not intended for public access!

Parameters

model – Pyomo ConcreteModel of the EnergySystem instance

abstract declare_component_constraints(ensys, model)[source]

Abstract method to create (conventional) component constraints.

con_couple_bi_ex_and_cap()[source]

Constraint to couple the global existence binary variable with the capacity variable. If the component does not exist, the capacity must take a value of 0. Note: The availability of the required ‘capacity_max’ parameter is checked during initialization. E.g.:
CAP <= BI_EX * capacity_max

Method is not intended for public access!

con_cap_min()[source]

Constraint to set the minimum capacity of a component (based on its basic variable). If a binary existence variable is declared, the minimal capacity is only enforced if the component exists. E.g.:
CAP >= capacity_min * BI_EX or
CAP >= capacity_min

Method is not intended for public access!

con_cap_modular()[source]

Constraint to calculate the nominal capacity of a component from the product of the capacity per module and the number of existing modules. E.g.:
CAP == capacity_per_module * summation(BI_MODULE_EX)

Method is not intended for public access!

con_modular_sym_break()[source]

Constraint to state, that the next module can only be built if the previous one already exists (symmetry break constraint for components consisting of multiple modules). E.g.:
BI_MODULE_EX[2] <= BI_MODULE_EX[1]

Method is not intended for public access!

con_couple_existence_and_modular()[source]

Constraint to couple the global existence binary variable with the binary existence status of the first module. All other modules are indirectly coupled via symmetry breaks. E.g.:
BI_EX >= BI_MODULE_EX[1]

Method is not intended for public access!

con_bi_var_ex_and_op_relation(model)[source]

Constraint to set a relationship between the binary variables for existence and operation. A component can only be operated if it exists. E.g.:
BI_OP[p, t] <= BI_EX

Method is not intended for public access!

abstract con_operation_limit(model)[source]

Constraint to limit the operation (value of the basic variable) of a component (MWh) by its nominal power (MW) multiplied with the number of hours per time step (not for Storage because it is already a capacity!). E.g.:
Q[p, t] <= CAP * dt (Conversion, Sink, Source)
SOC[p, t] <= CAP (Storage)
Q_IN[p, t] <= CAP * dt (Bus)

Method is not intended for public access!

con_couple_op_binary_and_basic_var(model)[source]

Constraint to couple the binary operation variable (is available), with the basic variable of the component. Therefore, the “capacity_max” parameter serves for overestimation (BigM). E.g.:
Q[p, t] <= capacity_max * BI_OP[p, t] * dt

Method is not intended for public access!

get_objective_function_contribution(ensys, model)[source]

Calculate the objective function contributions of the component and add the values to the component dictionary “comp_obj_dict”.

Method is not intended for public access!

Parameters

  • ensys – Instance of the EnergySystem class

  • model – Pyomo ConcreteModel of the EnergySystem instance

serialize()[source]

This method collects all relevant input data and optimization results from the Component instance, and returns them in an ordered dictionary.

Returns

OrderedDict