general package

Please, have a look to the following general modules

Firstly, the main modules to build an energy optimisation model are presented :

Elements module

This module includes the optimization elements (quantities, constraints and objectives) formulated in LP or MILP

• Quantity : related to the decision variable or parameter

• Constraint : related to the optimization problem constraints 4 categories of constraints :

  • Constraint: to define a constraint object

  • DefinitionConstraint: to calculate and define quantities or for physical

  constraints - TechnicalConstraint: linked with technical constraints - ActorConstraint: constraint decided by the actors 2 types of constraints: - Constraints : basic constraint - DynamicConstraint: basic constraint depending on the time

• Objective : related to the objective function

class omegalpes.general.optimisation.elements.ActorConstraint(exp, name='ActCST0', description='', active=True, parent=None)

Bases: Constraint

Description

Defining a category of constraint: ActorConstraint (see: DynamicConstraint, TechnicalConstraint) To model a constraint which is due to actor decisions. Must be different from Definition and Technical constraints. This kind of constraint is mainly a negotiable constraint.

example: to have a minimal level of energy consumption over a period. Constraint : min_energy

deactivate_constraint()

An actor’s constraint can be deactivated : - To compare scenarios - To try a less constrained problem

class omegalpes.general.optimisation.elements.ActorDynamicConstraint(exp_t, t_range='for t in time.I', name='ActDynCST0', active=True, description='Actor and dynamic constraint', parent=None)

Bases: DynamicConstraint, ActorConstraint

Description

Defining a category of constraint: ActorDynamicConstraint (see: DynamicConstraint, ActorConstraint) Must be different from Definition and Technical constraints. This kind of constraint is mainly a negotiable constraint.

example: to operate an energy unit only on defined periods. Constraint: daily_dynamic_constraint

class omegalpes.general.optimisation.elements.Constraint(exp, name='CST0', description='', active=True, parent=None)

Bases: object

Description

Class that defines a constraint object

Attributes

• name: name of the constraint

• description: a description of the constraint

• active: False = non-active constraint; True = active constraint

• exp: (str) : expression of the constraint

• parent: (unit) : this constraint belongs to this unit

Note

Make sure that all the modifications on Constraints are made before adding the unit to the Model (OptimisationModel.addUnit()).

class omegalpes.general.optimisation.elements.DailyDynamicConstraint(exp_t, time, init_time: str = '00:00', final_time: str = '23:00', name='daily_dynamic_constraint', description='daily dynamic constraint', active=True, parent=None)

Bases: ActorDynamicConstraint

Description

Class that defines a daily dynamic constraint for a time range

Ex: Constraint applying between 7am and 10:30pm

ex_cst = DailyDynamicConstraint(exp_t, time, init_h=”7:00”, final_h=”10:30”, name=’ex_cst’)

Attributes

• name (str) : name of the constraint

• exp_t (str) : expression of the constraint

• init_time (str) : starting time of the constraint in the format:

“HH:MM”, consistent with the dt value. - final_time (str) : ending time of the constraint in the format: “HH:MM”, consistent with the dt value. - description (str) : description of the constraint - active (bool) : defines if the constraint is active or not - parent (OptObject) : parent of the constraint

class omegalpes.general.optimisation.elements.DefinitionConstraint(exp, name='DefCST0', description='Constraint for definitions', active=True, parent=None)

Bases: Constraint

Description

Defining a category of constraint: DefinitionConstraint for imposed mathematical relation constraints, which may be physical. They are used to calculate and define quantities, or to reprensent physical phenomenon. Must be different from Technical and Actor constraints. This kind of constraint is by nature non-negotiable

Definition constraint: added to the model to calculate a quantity or define it considering an other.

example: the definition of e_tot: calc_e_tot (e_tot = LpSum(e))

Physical constraint: to model a constraint which is linked to the physics.

example: not implemented yet, see DefinitionDynamicConstraint

class omegalpes.general.optimisation.elements.DefinitionDynamicConstraint(exp_t, t_range='for t in time.I', name='DefDynCST0', description='dynamic constraint for definition', active=True, parent=None)

Bases: DynamicConstraint, DefinitionConstraint

Description

Defining a category of constraint: DefinitionDynamicConstraint on the time. (see: DynamicConstraint, DefinitionConstraint) Must be different from Technical and Actor constraints. This kind of constraint is by nature non-negotiable

DefinitionDynamicConstraint: to calculate a quantity or define it considering an other quantity and depending on the time.

example: the definition of a capacity def_capacity (energy[t] <= capacity at each time step t)

Physical constraint: to model physical constraints.

example: the power balance in an Energy node: power_balance

(LpSum(p_production_unit[t] for the set of production units connected to the energy node) = LpSum(p_consumption_unit[t] for the consumption units connected to the energy node at each time step t)

class omegalpes.general.optimisation.elements.DynamicConstraint(exp_t, t_range='for t in time.I', name='DCST0', description='dynamic constraint', active=True, parent=None)

Bases: Constraint

Description

Class that defines a constraint depending on the time. NB : Mandatory for PuLP

class omegalpes.general.optimisation.elements.ExtDynConstraint(exp_t, t_range='for t in time.I', name='EDCST0', active=True, description='Non-physical and dynamic constraint', parent=None)

Bases: DynamicConstraint, ExternalConstraint

Description

DEPRECATED: please use ActorDynamicConstraint

Defining a constraint both external and dynamic (see: DynamicConstraint, ExternalConstraint)

class omegalpes.general.optimisation.elements.ExternalConstraint(exp, name='ExCST0', description='', active=True, parent=None)

Bases: Constraint

Description

DEPRECATED: please use ActorConstraint

Defining a special type of constraint: the external constraint

• This constraint does not translate a physical constraint

• This constraint defines an external constraint, which could be relaxed

deactivate_constraint()

An external constraint can be deactivated : - To compare scenarios - To try a less constrained problem

class omegalpes.general.optimisation.elements.HourlyDynamicConstraint(exp_t, time, init_h: int = 0, final_h: int = 24, name='HDCST0', description='hourly dynamic constraint', active=True, parent=None)

Bases: ActorDynamicConstraint

Description

DEPRECATED: please use DailyDynamicConstraint

Class that defines an dynamic contraint for a time range

Ex: Constraint applying between 7am and 10pm

ex_cst = HourlyDynamicConstraint(exp_t, time, init_h=7, final_h=22, name=’ex_cst’)

Attributes

• name (str) : name of the constraint

• exp_t (str) : expression of the constraint

• init_h (int) : hour of beginning of the constraint [0-23]

• final_h (int) : hour of end of the constraint [1-24]

• description (str) : description of the constraint

• active (bool) : defines if the constraint is active or not

• parent (OptObject) : parent of the constraint

class omegalpes.general.optimisation.elements.Objective(exp, name='OBJ0', description='', active=True, weight=1, unit='s.u.', pareto=False, parent=None)

Bases: object

Description

Class that defines an optimisation objective

Attributes

• name (str) :

• exp (str) :

• description (str) :

• active (bool) :

• weight (float) : weighted factor of the objective

• parent (unit)

• unit (str) : unit of the cost expression

• pareto (str)if True, OMEGAlpes calculates a pareto front based on

  this objective (two objectives needed)

Methods

• _add_objectives_list()

• _add_pareto_objectives_list()

Note

Make sure that all the modifications on Objectives are made before adding the unit to the OptimisationModel, otherwise, it won’t be taken into account

class omegalpes.general.optimisation.elements.Quantity(name='var0', opt=True, unit='s.u', vlen=None, value=None, description='', vtype='Continuous', lb=None, ub=None, parent=None)

Bases: object

Description

Class that defines what is a quantity. A quantity can wether be a decision variable or a parameter, depending on the opt parameter

Attributes

• name (str) : the name of the quantity

• description (str) : a description of the meaning of the quantity

• vtype (PuLP) : the variable type, depending on PuLP

  • LpBinary (binary variable)

  • LpInteger (integer variable)

  • LpContinuous (continuous variable)

• vlen (int) : size of the variable

• unit (str) : unit of the quantity

• opt (binary)

  • True: this is an optimization variable

  • False: this is a constant - a parameter

• value (float, list, dict) : value (unused if opt=True)

• ub, lb : upper and lower bounds

• parent (OptObject) : the quantity belongs to this unit

Note

Make sure that all the modifications on Quantity are made before adding the unit to the Model

get_value()

return the value of the quantity according the type of the value in order to be able to use it easily in print and plot methods: int -> int float -> float list -> list dict -> list ndarray –> list

get_value_with_date(unit=None)

return the values of the quantity associated to a date in a dataframe if the values are a list or a dict (only).

class omegalpes.general.optimisation.elements.TechnicalConstraint(exp, name='TechCST0', description='Technical constraint', active=True, parent=None)

Bases: Constraint

Description

Defining a category of constraint: TechnicalConstraint. To model a constraint which is linked to technical issues Must be different from Definition and Actor constraints. This kind of constraint is mainly a negotiable constraint.

example: not implemented yet, see TechnicalDynamicConstraints

deactivate_constraint()

An technical constraint can be deactivated : - To compare scenarios - To try a less constrained problem

class omegalpes.general.optimisation.elements.TechnicalDynamicConstraint(exp_t, t_range='for t in time.I', name='TechCST0', active=True, description='Technical and dynamic constraint', parent=None)

Bases: DynamicConstraint, TechnicalConstraint

Description

Defining a category of constraint: TechnicalDynamicConstraint depending on the time. (see: DynamicConstraint, TechnicalConstraint) Must be different from Definition and Actor constraints. This kind of constraint is mainly a negotiable constraint.

example: an energy unit may not be able to stop in one time step, but several. The power decreases as a ramp shape: set_max_ramp_down

Core module

This module define the main Core object on which the energy units and actors will be based

class omegalpes.general.optimisation.core.OptObject(name='U0', description='Optimization object', verbose=True)

Bases: object

Description

OptObject class is used as an “abstract class”, i.e. it defines some general attributes and methods but doesn’t contain variable, constraint nor objective. In the OMEGAlpes package, all the subsystem models are represented by a unit. A model is then generated adding OptObject to it. Variable, objective and constraints declarations are usually done using the __init__ method of the OptObject class.

Attributes

• name

• description

• _quantities_list : list of the quanitities of the OptObject (active or not)

• _constraints_list : list of the constraints of the OptObject(active or not)

• _technical_constraints_list : list of the constraints of the OptObject (active or not)

• _objectives_list : list of the objectives of the OptObject (active or not)

Methods

• __str__: defines the

• __repr__: defines the unit with its name

• get_constraints_list

• get_constraints_name_list

• get_external_constraints_list

• get_external_constraints_name_list

• get_objectives_list

• get_objectives_name_list

• get_quantities_list

• get_quantities_name_list

• deactivate_optobject_external_constraints

Note

The OptObject class shouldn’t be instantiated in a python script, except if you want to create your own model from the beginning. In this case, one should consider creating a new class NewModel(OptObject).

deactivate_optobject_external_constraints(ext_cst_name_list=None)

Enable to remove an external constraint linked with an OptObject

Parameters:

ext_cst_name_list – list of external constraint that would be removed

get_actor_constraints_list()

Get the technical constraints associated with the unit as a dictionary shape [‘constraint_name’ , constraint]

get_actor_constraints_name_list()

Get the names of the external constraints associated with the unit

get_constraints_list()

Get the constraints associated with the unit as a dictionary shape [‘constraint_name’ , constraint]

get_constraints_name_list()

Get the names of the constraints associated with the unit

get_objectives_list()

Get objectives associated with the unit as a dictionary shape [‘objective_name’ , objective]

get_objectives_name_list()

Get the names of the objectives associated with the unit

get_quantities_list()

Get the quantities associated with the unit as a dictionary shape [‘quantity_name’ , quantity]

get_quantities_name_list()

Get the names of the quantities associated with the unit

get_technical_constraints_list()

Get the technical constraints associated with the unit as a dictionary shape [‘constraint_name’ , constraint]

get_technical_constraints_name_list()

Get the names of the external constraints associated with the unit

Time module

This module creates the Time object

class omegalpes.general.time.TimeUnit(start='01/01/2018', end=None, periods=None, dt=1, verbose=True)

Bases: object

Description

Class defining the studied time period.

Attributes

• DATES : dated list of simulation steps

• DT : delta t between values in hours (int or float), i.e. 1/6 will be 10 minutes.

• LEN : number of simulation steps (length of DATES)

• I : index of time ([0 : LEN])

get_date_for_index(index)

Getting a date for a given index

Parameters:

index – int value for the index of the wanted dated, between 0 and LEN (it must be in the studied period)

property get_days

Getting days for the studied period

Return all_days:

list of days of the studied period

get_index_for_date(date='YYYY-MM-DD HH:MM:SS')

Getting the index associated with a date

Parameters:

date – date the index of is wanted. Format YYYY-MM-DD HH:MM:SS, must be within the studied period and consistent with the timestep value

get_index_for_date_range(starting_date='YYYY-MM-DD HH:MM:SS', end=None, periods=None)

Getting a list of index for a date range

Parameters:

• starting_date – starting date of the wanted index

• end – ending date of the wanted index

• periods – number of periods from the starting_date of the wanted index

Return index_list:

list of indexes for the given dates

get_non_working_dates(month_range=range(0, 12), hour_range=range(0, 24), country='France')

get_non_working_days(country='France')

get_working_dates(month_range=range(0, 12), hour_range=range(0, 24), country='France')

get_working_days(country='France')

print_studied_period()

omegalpes.general.time.convert_european_format(date)

Converting a date with an european format DD/MM/YYYY into a datetime format YYYY-MM-DD or return

Parameters:

date – date in european format

Returns:

date in format datetime

Model module

This module enables to fill the optimization model and formulate it in LP or MILP based on the package PuLP (LpProblem)

class omegalpes.general.optimisation.model.OptimisationModel(time, name='optimisation_model')

Bases: LpProblem

Description

This class includes the optimization model formulated in LP or MILP based on the package PuLP (LpProblem)

add_nodes(*nodes)

Add nodes and all connected units to the model Check that the time is the same for the model and all the units

Parameters:

nodes – EnergyNode

add_nodes_and_actors(*nodes_or_actors)

Add nodes, actors and all connected units to the model Check that the time is the same for the model and all the units

Parameters:

nodes_or_actors – EnergyNode or Actor type

get_model_constraints_list()

Gets constraints of the model

get_model_constraints_name_list()

Gets the names of the constraints of the model

get_model_objectives_list()

Gets objectives of the model

get_model_objectives_name_list()

Gets the names of the objectives of the model

get_model_quantities_list()

Gets quantities of the model

get_model_quantities_name_list()

Gets the names of the quantities of the model

solve_and_update(solver: LpSolver = None, find_infeasible_cst_set=False, pareto_step=0.1) → None

Solves the optimization model and updates all variables values.

Parameters:

• solver (LpSolver) – Optimization solver

• pareto_step – if there are pareto objectives, you can change the step to calculate the pareto front

update_units()

Updates all units values with optimization results

omegalpes.general.optimisation.model.check_if_unit_could_have_parent(unit)

Checks if the unit has an associated parent

Parameters:

unit – unit which parents will be checked

omegalpes.general.optimisation.model.compute_gurobi_IIS(gurobi_exe_path='C:\\gurobi810\\win64\\bin', opt_model=None, MPS_model=None)

Identifies the constraints in a .ilp file

Parameters:

• gurobi_exe_path – Path to the gurobi solver “gurobi_cl.exe”

• opt_model – OptimisationModel to whom compute IIS

• MPS_model – name of the mps model

Then, utils methods are developped and are presented in the following module:

Input Data module

This module includes the following utils for input data management

It contains the following methods:

• select_csv_file_between_dates() : select data in a .csv file between two dates

• read_enedis_data_csv_file() : select and rearrange the data in a .csv file of Enedis (the French Distribion System Operator company), possibly between two dates

omegalpes.general.utils.input_data.read_enedis_data_csv_file(file_path=None, start=None, end=None)

Rearrange the Enedis data in cvs file in oder to have a Dataframe of the following form

DD MM YYYY HH:00 ; a DD MM YYYY HH:30 ; b …

Parameters:

• file_path – path of the file to rearrange

• start – DD MM YYYY HH:00 : first date which should be considered

• end – DD MM YYYY HH:00 : last date which should be considered

Returns:

df_list: the data as a list

omegalpes.general.utils.input_data.resample_data(input_list=None, dt_origin=1.0, dt_final=1.0, fill_config='ffill', pick_config='mean')

Changing data set in a dt_origin time step into data set in a dt_final time step :param input_list: list to be resample (list or dict) :param dt_origin: the time step of the input dataset (in hours) :param dt_final: the wanted time step for the output dataset (in hours) :param fill_config: choose the configuration of filling when dt_origin > dt_final by default: ffil, keeping the same data over the time steps other way: interpolate, taking into account the time steps) :param pick_config: choose the configuration of picking when dt_origin < dt_final by default: “mean” which determines the mean value of the time steps to be reduced :return: output_list: resampled list (pandas Series)

omegalpes.general.utils.input_data.select_csv_file_between_dates(file_path=None, start='DD/MM/YYYY HH:MM', end='DD/MM/YYYY HH:MM', v_cols=[], sep=';')

Select data in a .csv file between two dates

Parameters:

• file_path – path of the file to rearrange

• start – DD MM YYYY HH:00 : first date which should be considered

• end – DD MM YYYY HH:00 : last date which should be considered

• v_cols – columns which should be considered

Returns:

df: a dataframe considering the dates

Output Data module

This module includes the following utils for output data management

It contains the following methods:

• save_energy_flows() : Save the optimisation results in a .csv file

omegalpes.general.utils.output_data.save_energy_flows(*nodes, file_name=None, sep='\t', decimal_sep='.')

Save the optimisation results in a .csv file

Parameters:

• nodes – one or several nodes from which should be collected the data

• file_name – name of the file to save the data

• sep – separator for the data

• decimal_sep – separator dor the decimals of the data

Plots module

This module includes the following display utils:

• plot_node_energetic_flows() : enables one to plot the energy flows through an EnergyNode

• plot_energy_mix() : enables one to plot the energy flows connected to a node

• plot_pareto2D() : enables one to plot a pareto front based on two quantities

• plot_quantity() : enables one to plot easily a Quantity

• plot_quantity_bar() : enables one to plot easily a Quantity as a bar

• sum_quantities_in_quantity() : enables one to to plot several quantities in one once the optimisation is done

omegalpes.general.utils.plots.plot_energy_mix(node)

omegalpes.general.utils.plots.plot_node_energetic_flows(node)

Description

This function allows to plot the energy flows through an EnergyNode

The display is realized :

• with histograms for production and storage flow

• with dashed curve for consumption flow

Parameters:

node – EnergyNode

omegalpes.general.utils.plots.plot_pareto2D(model, quantity_1, quantity_2, title=None, legend_on=True)

Description

Plot a Pareto front for two quantities. Before using it, you should have added in your model two objectives with the pareto parameter activated (pareto=True)

Parameters

Parameters:

• model

• quantity_1 – the first quantity for the pareto front

• quantity_2 – the second quantity for the pareto front

• title

omegalpes.general.utils.plots.plot_quantity(time, quantity, fig=None, ax=None, color=None, label=None, title=None)

Description

Function that plots a OMEGAlpes.general.optimisation.elements.Quantity

Parameters

• time: TimeUnit for the studied horizon as defined in general.time

• quantity: OMEGAlpes.general.optimisation.elements.Quantity

• fig: Figure as defined in matplotlib.pyplot.Figure

• ax: axes as defined in matplotlib.pyplot.Axes

• color: color of the plot

• label: label for the quantity

• title: title of the plot

Returns

• arg1 the matplotlib.pyplot.Figure handle object

• arg2 the matplotlib.pyplot.Axes handle object

• arg3 the matplotlib.pyplot.Line2D handle object

omegalpes.general.utils.plots.plot_quantity_bar(time, quantity, fig=None, ax=None, color=None, label=None, title=None)

Description

Function that plots a OMEGALPES.general.optimisation.elements.Quantity as a bar

Attributes

• quantity is the OMEGALPES.general.optimisation.elements.Quantity

• fig could be None, a matplotlib.pyplot.Figure or Axes for multiple plots

Returns

• arg1 the matplotlib.pyplot.Figure handle object

• arg2 the matplotlib.pyplot.Axes handle object

• arg3 the matplotlib.pyplot.Line2D handle object

omegalpes.general.utils.plots.sum_quantities_in_quantity(quantities_list=[], tot_quantity_name='sum_quantity')

Description

Function that creates a new quantity gathering several values of quantities Should be used in order to plot several quantities in one once the optimisation is done

Attributes

• quantities : a list of Quantities (OMEGALPES.general.optimisation.elements.Quantity)

• tot_quantity_name : string : name of the new quantity

Returns

• tot_quantity : the new quantity created and filled

Maths module

This module includes the following maths utils

It contains the following methods:

• def_abs_value() : Define easily absolute value for quantity

omegalpes.general.utils.maths.def_abs_value(quantity, q_min, q_max)

Parameters:

• quantity – Quantity whose absolute value is wanted

• q_min – Minimal value of the quantity (negative value)

• q_max – Maximal value of the quantity (positive value)

Returns:

A new Quantity whose values equal absolute values of the initial Quantity