API Reference

Base.copy(model_copy::ModelEC)

Create a copy of a ModelEC opject

Arguments

• model_copy::ModelEC: model to copy

Base.deepcopy(model_copy::ModelEC)

Create a deepcopy of a ModelEC opject

Arguments

• model_copy::ModelEC: model to copy

Base.zero(::ModelEC)

Function zero to represent the empty ModelEC

_jump_to_dict

Function to turn a JuMP model to a dictionary

_print_summary(io::IO, model::AbstractEC)

Print a plain-text summary of model to io.

_verify_data(data::Dict)

Function to verify the data loaded from the disk (Not yet implemented)

_verify_users_data(users_data::Dict)

Function to verify the users data loaded from the disk

add_EC_economics_summary!(output_list::Vector, ECModel::AbstractEC)

Function to create the output dataframe of the economics of the EC

add_EC_peak_summary!(output_list::Vector, ECModel::AbstractEC)

Function to create the output dataframe of peak power for the EC

add_branching_priorities!(ECModel::AbstractEC, ::Any) end

General fallback for branching priorities

add_info_solution_summary!(output_list::Vector, ECModel::AbstractEC)

Utility function to create the dataframe to report the status of the optimization. It adds a dataframe named info_solution to output_list with the solve time and the termination status of the optimization.

Arguments

• output_list::Vector: The list of dataframes to be saved
• ECModel::AbstractEC: The EC model to be built

add_notations!(ECModel::AbstractEC, ::Any)

General fallback for notations

add_users_design_summary!(output_list::Vector, ECModel::AbstractEC, user_set::AbstractVector)

Utility function to create the output dataframe of design capacity. It adds a dataframe with the peak demand, yearly demand, and optimal size of the system for each user.

Arguments

• output_list::Vector: The list of dataframes to be saved
• ECModel::AbstractEC: The EC model to be built
• user_set::AbstractVector: The user set to be considered

add_users_economics_summary!(output_list::Vector, ECModel::AbstractEC, user_set::AbstractVector)

Function to create the output dataframe of the users' economics. It adds a dataframe with the NPV, CAPEX, OPEX, yearly revenues, and other economic indicators for each user.

Arguments

• output_list::Vector: The list of dataframes to be saved
• ECModel::AbstractEC: The EC model to be built
• user_set::AbstractVector: The user set to be considered

add_users_peak_summary!(output_list::Vector, ECModel::AbstractEC, user_set::AbstractVector)

Function to create the output dataframe of peak power. It adds a dataframe with the peak power of each user for each peak period.

Arguments

• output_list::Vector: The list of dataframes to be saved
• ECModel::AbstractEC: The EC model to be built
• user_set::AbstractVector: The user set to be considered

Function to get the list of the assets for a user

Function to get the list of the assets for a user in a list of elements

Function to get the list of the assets for a user

Function to get the list of the assets for a user in a list of elements except a list of given types

Function to get the asset type of a component

build_base_model!(ECModel::AbstractEC, optimizer)

Creates the base optimization model for all the EC models

Arguments

• ECModel: EC model object
• optimizer: optimizer object; any optimizer from JuMP
• use_notations: boolean; if true, the model will be created using the direct mode to create the JuMP model

Returns

It returns the ECModel object with the base model created

build_base_utility!(ECModel::AbstractEC, base_group::AbstractGroupANC; base_model=nothing)

When in the CO case the ANC model is used as base case, then this function builds the corresponding constraint

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study.
• base_group::AbstractGroupANC: Type of the base case to consider
• base_model::ModelEC: Model of the base case to consider

Returns

• BaseUtility: JuMP expression of the base utility

build_base_utility!(ECModel::AbstractEC, base_group::AbstractGroupNC; base_model=nothing)

When in the CO case the NC model is used as base case, then this function builds the corresponding constraint

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study.
• base_group::AbstractGroupNC: Type of the base case to consider
• base_model::ModelEC: Model of the base case to consider

Returns

• BaseUtility: JuMP expression of the base utility

build_base_utility!(ECModel::AbstractEC, no_aggregator_group::AbstractGroupANC)

When in the CO case the ANC model is used as reference case for when the aggregator is not in the group, then this function builds the corresponding constraint

Not implemented

build_least_profitable!(
    ECModel::AbstractEC, base_group::AbstractGroup;
    no_aggregator_group::AbstractGroup=GroupNC(),
    add_EC=true,
    relax_combinatorial=false,
    use_notations=false,
    base_model=nothing,
)

Function to build the model to identify the least profitable coalition. This function builds the model in the ECModel object to identify the least profitable coalition using a MILP model.

Arguments

• ECModel::AbstractEC: EC Model of the EC to study.
• base_group::AbstractGroup: Type of the base case to consider
• no_aggregator_group::AbstractGroup=GroupNC(): Type of the base case to consider when no aggregator is in the coalition
• add_EC::Bool=true: Flag to include the EC in the coalition
• relax_combinatorial::Bool=false: Flag to relax the combinatorial part of the MILP model
• use_notations::Bool=false: Flag to use notations in the model
• base_model::ModelEC=nothing: Model of the base case to consider

build_model!(ECModel::AbstractEC; kwargs...)

Build the mathematical problem for the EC.

build_model!(group_type::AbstractGroup, ECModel::AbstractEC, optimizer; use_notations=false)

Build function model for generic EnergyCommunity model. This functions triggers specific functions for the different aggregation types.

In particular, first the function build_base_model! is called to build the base model of the EC. Then, the function build_specific_model! is called to build the specific model of the EC dependin on the group type. Finally, the function set_objective! is called to set the objective of the EC, based on their group type.

build_no_agg_utility!(ECModel::AbstractEC, no_aggregator_group::AbstractGroupANC; base_model=nothing)

When in the CO case the ANC model is used as reference case for when the aggregator is not in the group, then this function builds the corresponding constraint

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study.
• no_aggregator_group::AbstractGroupANC: Type of the base case to consider
• base_model::ModelEC: Model of the base case to consider

Returns

• SW: JuMP expression of the Social Welfare

buildnoaggutility!(ECModel::AbstractEC, noaggregator_group::AbstractGroupNC; kwargs...)

When the NC case is the reference value when no aggregator is available, then no changes in the model are required

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study.
• no_aggregator_group::AbstractGroupNC: Type of the base case to consider

Returns

• SW: JuMP expression of the Social Welfare; the same as in the input model

build_no_agg_utility!(ECModel::AbstractEC, no_aggregator_group::Any)

Not implemented case

build_noagg_least_profitable(ECModel::ModelEC; use_notations=false, optimizer=nothing, base_model=nothing)

Function to create a specialized model to identify the least profitable coalition for an energy community of ANC type.

Arguments

• ECModel::ModelEC: Model of the community
• use_notations::Bool=false: Flag to use notations in the model
• optimizer::Optimizer=nothing: Optimizer to use
• base_model::ModelEC=nothing: Model of the base case to consider

build_specific_model!(::AbstractGroupANC, ECModel::AbstractEC)

Set the ANC-specific model for the EC

build_specific_model!(::AbstractGroupCO, ECModel::AbstractEC)

Set the CO-specific model for the EC

build_specific_model!(::AbstractGroupNC, ECModel::AbstractEC)

Set the NC-specific model for the EC. It adds the P_agg expression only being equal to the sum of the power supplied by the users to the grid.

Arguments

• group_type::AbstractGroupNC: The type of group model
• ECModel::AbstractEC: The EC model to be built

Returns

• ECModel::AbstractEC: The EC model with the specific model built

business_plan(ECModel::AbstractEC, profit_distribution=nothing, user_set_financial=nothing)

Function to describe the business plan

Arguments

• ECModel::AbstractEC: Energy Community model
• profit_distribution: (optional) DenseAxisArray with the profit distribution by user
• user_set_financial: (optional) User set to be considered for the financial analysis

Returns

The output value is a DataFrame with the business plan information

business_plan_plot(ECModel::AbstractEC, ...)

Function to plot the business plan of the EnergyCommunity.

Arguments

• ECModel::AbstractEC: Energy Community model
• profit_distribution: (optional) Dictionary with the profit distribution by user
• user_set_financial: (optional) User set to be considered for the financial analysis
• plot_struct: (optional) Dictionary with the structure of the plot. The keys are the labels of the bars and the values are a list of tuples with the sign and the name of the variable to be plotted. Example is Dict("CAPEX" => [(-1, :CAPEX)]) for plotting the CAPEX with a negative sign.
• xlabel: (optional) Label for the x-axis
• ylabel: (optional) Label for the y-axis
• title: (optional) Title of the plot
• legend: (optional) Position of the legend
• color: (optional) Color of the bars
• xrotation: (optional) Rotation of the x-axis labels
• bar_width: (optional) Width of the bars
• grid: (optional) Grid visibility
• framestyle: (optional) Style of the frame
• barmode: (optional) Mode of the bars
• scaling_factor: (optional) Scaling factor for the values
• kwargs: (optional) Additional arguments to be passed to Plots.bar function

calculate_demand(ECModel::AbstractEC)

Function to calculate the demand by user

Arguments

• ECModel: EC model object

Returns

It returns the demand by user and the whole EC as a DenseAxisArray

calculate_grid_export(ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid export for the energy community and users. Output is normalized with respect to the demand when per_unit is true

Returns

It returns a DenseAxisArray containing the power fed to the grid for each user and the whole aggregate

calculate_grid_export(::AbstractGroupANC, ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid export for the Aggregated Non Cooperative case. Output is normalized with respect to the demand when per_unit is true

Returns

It returns a DenseAxisArray containing the power fed to the grid for each user and the whole aggregate

calculate_grid_export(::AbstractGroupCO, ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid export for the Cooperative case. Output is normalized with respect to the demand when per_unit is true

Returns

Returns a DenseAxisArray that contains the reliance on the grid supply for each user and the aggregation

calculate_grid_export(::AbstractGroupNC, ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid export for the Non-Cooperative case Output is normalized with respect to the demand when per_unit is true

Returns

Returns a DenseAxisArray that contains the reliance on the grid supply for each user and the aggregation

calculate_grid_import(ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid usage for the energy community and users. Output is normalized with respect to the demand when per_unit is true

Returns

It returns a DenseAxisArray containing the power withdrawn from the grid for each user and the whole aggregate

calculate_grid_import(::AbstractGroupANC, ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid usage for the Aggregated Non Cooperative case. Output is normalized with respect to the demand when per_unit is true

Returns

It returns a DenseAxisArray containing the power withdrawn from the grid for each user and the whole aggregate

calculate_grid_import(::AbstractGroupCO, ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid usage for the Cooperative case. Output is normalized with respect to the demand when per_unit is true

Returns

Returns a DenseAxisArray that describes the reliance on the grid withdrawal for each user and the aggregation

calculate_grid_import(::AbstractGroupNC, ECModel::AbstractEC; per_unit::Bool=true)

Calculate grid usage for the Non Cooperative case. Output is normalized with respect to the demand when per_unit is true

Returns

Returns a DenseAxisArray that describes the reliance on the grid withdrawal for each user and the aggregation

calculate_production(ECModel::AbstractEC)

Function to calculate the energy production by user

Arguments

• ECModel: EC model object

Returns

It returns the production by user and the whole EC as a DenseAxisArray

calculate_production_shares(ECModel::AbstractEC; per_unit::Bool=true)

Calculate energy ratio by energy production resource for a generic group Output is normalized with respect to the demand when per_unit is true

Arguments

• ECModel: EC model object
• per_unit: boolean; if true, the output is normalized with respect to the demand

Returns

It returns a DenseAxisArray describing the share of energy production by energy resource by user and the entire system, optionally normalized with respect to the demand of the corresponding group, when per_unit is true

calculate_self_consumption(ECModel::AbstractEC; per_unit::Bool=true)

Calculate the demand that each user meets using its own sources, or self consumption. Output is normalized with respect to the demand when per_unit is true

Arguments

• ECModel: EC model object
• per_unit: boolean; if true, the output is normalized with respect to the demand

Returns

It returns a DenseAxisArray describing the self consumption for each user and the aggregation, optionally normalized with respect to the demand of the corresponding group, when per_unit is true

calculate_self_production(ECModel::AbstractEC; per_unit::Bool=true)

Calculate the self production for each user. Output is normalized with respect to the demand when per_unit is true

Arguments

• ECModel: EC model object
• per_unit: boolean; if true, the output is normalized with respect to the demand

Returns

It returns a DenseAxisArray describing the self production for each user and the aggregation, optionally normalized with respect to the demand of the corresponding group, when per_unit is true

calculate_shared_consumption(ECModel::AbstractEC; per_unit::Bool=true)

Calculate the demand that each user meets using its own sources or other users. When onlyshared is false, also self consumption is considered, otherwise only shared consumption. Output is normalized with respect to the demand when perunit is true

Returns

It returns a DenseAxisArray containing the time-dependent share of power withdrawn from the grid but consumed by another user for each user and the whole aggregate

calculate_shared_consumption(::AbstractGroupANC, ECModel::AbstractEC; per_unit::Bool=true, only_shared::Bool=false)

Calculate the demand that each user meets using its own sources or other users for the Aggregated Non Cooperative case. In this case, there can be shared energy, non only self consumption. When onlyshared is false, also self consumption is considered, otherwise only shared energy. Shared energy means energy that is shared between Output is normalized with respect to the demand when perunit is true

Returns

It returns a DenseAxisArray containing the time-dependent share of power withdrawn from the grid but produced by another user for each user and the whole aggregate

calculate_shared_consumption(::AbstractGroupCO, ECModel::AbstractEC; per_unit::Bool=true, only_shared::Bool=false)

Calculate the demand that each user meets using its own sources or other users for the Cooperative case. In the Cooperative case, there can be shared energy, non only self consumption. When onlyshared is false, also self consumption is considered, otherwise only shared energy. Shared energy means energy that is shared between Output is normalized with respect to the demand when perunit is true

Returns

It returns the shared consumption for each user and the aggregation

calculate_shared_consumption(::AbstractGroupNC, ECModel::AbstractEC; kwargs...)

Calculate the demand that each user meets using its own sources or other users for the Non-Cooperative case. In the Non-Cooperative case, there is no shared energy, only self consumption. Shared energy means energy that is shared between Output is normalized with respect to the demand when per_unit is true

Returns

It returns the shared consumption for each user and the aggregation

calculate_shared_production(ECModel::AbstractEC; per_unit::Bool=true)

Calculate the energy that each user produces and uses in its own POD or it is commercially consumed within the EC, when creaded. When onlyshared is false, also self production is considered, otherwise only shared energy. Output is normalized with respect to the demand when perunit is true

Returns

It returns a DenseAxisArray containing the time-dependent share of power fed to the grid but consumed by another user for each user and the whole aggregate

calculate_shared_production(::AbstractGroupANC, ECModel::AbstractEC; per_unit::Bool=true, only_shared::Bool=false)

Calculate the shared produced energy for the Aggregated Non Cooperative case. In this case, there can be shared energy between users, not only self production. When onlyshared is false, also self production is considered, otherwise only shared energy. Shared energy means energy that is shared between Output is normalized with respect to the demand when perunit is true

Returns

It returns a DenseAxisArray containing the time-dependent share of power fed to the grid but consumed by another user for each user and the whole aggregate

calculate_shared_production(::AbstractGroupCO, ECModel::AbstractEC; per_unit::Bool=true, only_shared::Bool=false)

Calculate the shared produced energy for the Cooperative case. In the Cooperative case, there can be shared energy between users, not only self production. When onlyshared is false, also self production is considered, otherwise only shared energy. Shared energy means energy that is shared between Output is normalized with respect to the demand when perunit is true

Returns

It returns a DenseAxisArray that contains the shared energy for each user and the aggregation

calculate_shared_production(::AbstractGroupNC, ECModel::AbstractEC; kwargs...)

Calculate the shared produced energy for the Non-Cooperative case. In the Non-Cooperative case, there is no shared energy between users, only self production. Output is normalized with respect to the demand when per_unit is true

Returns

It returns a DenseAxisArray that contains the shared energy for each user and the aggregation

calculate_time_shared_consumption(ECModel::AbstractEC)

Calculate the time series of the shared consumed energy for the Energy Community.

For every time step and user, this time series highlight the quantity of load that is met by using shared energy.

Returns

It returns a DenseAxisArray containing the time-dependent share of power withdrawn from the grid but produced by another user for each user and the whole aggregate

calculate_time_shared_consumption(::AbstractGroupANC, ECModel::AbstractEC; add_EC=true, kwargs...)

Calculate the time series of the shared consumed energy for the Aggregated Non Cooperative case. In the Aggregated Non Cooperative case, there can be shared energy between users, not only self production.

For every time step and user, this time series highlight the quantity of load that is met by using shared energy.

Returns

It returns a DenseAxisArray containing the time-dependent share of power withdrawn from the grid but produced by another user for each user and the whole aggregate

calculate_time_shared_consumption(::AbstractGroupCO, ECModel::AbstractEC; add_EC=true, kwargs...)

Calculate the time series of the shared consumed energy for the Cooperative case. In the Cooperative case, there can be shared energy between users, not only self production.

For every time step and user, this time series highlight the quantity of load that is met by using shared energy.

Returns

It returns a DenseAxisArray that quantifies the shared consumption for each user and the aggregation and time step

calculate_time_shared_consumption(::AbstractGroupNC, ECModel::AbstractEC; add_EC=true, kwargs...)

Calculate the time series of the shared consumed energy for the Cooperative case. In the Cooperative case, there can be shared energy between users, not only self production.

For every time step and user, this time series highlight the quantity of load that is met by using shared energy.

Returns

It returns a DenseAxisArray that quantifies the shared consumption for each user and the aggregation and time step

calculate_time_shared_production(ECModel::AbstractEC; kwargs...)

Calculate the time series of the shared consumed energy for the Energy Community.

For every time step and user, this time series highlight the quantity of production that meets needs by other users.

Returns

It returns a DenseAxisArray containing the time-dependent share of power fed to the grid but consumed by another user for each user and the whole aggregate

calculate_time_shared_production(::AbstractGroupANC, ECModel::AbstractEC; add_EC=true, kwargs...)

Calculate the time series of the shared produced energy for the Aggregated Non Cooperative case. In the Aggregated Non Cooperative case, there can be shared energy between users, not only self production.

For every time step and user, this time series highlight the quantity of production that meets needs by other users.

Returns

It returns a DenseAxisArray containing the time-dependent share of power fed to the grid but consumed by another user for each user and the whole aggregate

calculate_time_shared_production(::AbstractGroupCO, ECModel::AbstractEC; add_EC=true, kwargs...)

Calculate the time series of the shared produced energy for the Cooperative case. In the Cooperative case, there can be shared energy between users, not only self production.

For every time step and user, this time series highlight the quantity of production that meets needs by other users.

Returns

Returns a DenseAxisArray that contains the shared production for each user and the aggregation and time step

calculate_time_shared_production(::AbstractGroupNC, ECModel::AbstractEC; add_EC=true, kwargs...)

Calculate the time series of the shared produced energy for the Cooperative case. In the Cooperative case, there can be shared energy between users, not only self production.

For every time step and user, this time series highlight the quantity of production that meets needs by other users.

Returns

Returns a DenseAxisArray that contains the shared production for each user and the aggregation and time step

check_valid_data_dict(raw_dict_data::Dict)

Check whether the dictionary data has the needed components. The dictionary must have the keys "general", "users", and "market".

Function to get the components value of a dictionary

Function to get the components list of a dictionary

create_example_data(parent_folder, config_name::String = "default")

Create an example data for the Energy Community model. This function creates in the specified folder the necessary data to run the Energy Community model, based on the specified configuration name.

Arguments

• parent_folder: Parent folder where the example data will be created
• config_name: Configuration name to be used to create the example data Supported values: "default"

create_output_data(ecm_copy::ModelEC, number_of_solutions)

Function to create output data after the optimization for TheoryOfGames.jl. This functions obtains multiple solutions out of the optimization.

Arguments

• ecm_copy::ModelEC: Model of the community
• number_of_solutions::Int: Number of solutions to return

Returns

• output_data::Vector{NamedTuple}: Output data

data_sankey(ECModel::AbstractEC; name_units=nothing, norm_value=nothing, market_color = palette(:rainbow)[2], community_color = palette(:rainbow)[5], users_colors = palette(:default))

Function to create the input data for plotting any Sankey diagram representing the energy flows across the energy community

Arguments

• ECModel::AbstractEC: Energy Community model
• name_units: (optional) Labels used for the sankey diagram with the following order: "Market buy", [users labels], "Community", "Market sell", [users labels]
• norm_value: (optional) Normalization value for the flows
• market_color: (optional) Color of the market
• community_color: (optional) Color of the community
• users_colors: (optional) Colors of the users

Returns

• sank_data: Dictionary containing the data to plot the Sankey diagram, in agreement to SankeyPlots.jl package
  • "source": sources of the Sankey
  • "target": targets of the Sankey
  • "value": value of each flow
  • "labels": labels of the Sankey
  • "colors": colors of the Sankey
  • "layer": layer of the Sankey
  • "order": order of the Sankey

Function to get the list of devices for a user

explode_data(ECModel::AbstractEC)

Return main data elements of the dataset of the ECModel: general parameters, users data and market data, retrieved from the data dictionary of the ECModel.

Arguments

• ECModel::AbstractEC: Energy Community model

Returns

• general_data::Dict: General data of the ECModel
• users_data::Dict: Users data of the ECModel
• market_data::Dict: Market data of the ECModel

Return main data elements of the dataset: general parameters, users data and market data

Function get field that throws an error if the field is not found

Function to get the components value of a dictionary, with default value

Function to get the components value of a dictionary

Function to safely get a field of a dictionary with default value

finalize_results!(::AbstractGroupANC, ECModel::AbstractEC)

Function to finalize the results of the Aggregated Non Cooperative model after the execution

finalize_results!(::AbstractGroupCO, ECModel::AbstractEC)

Function to finalize the results of the Cooperative model after the execution Nothing to do

finalize_results!(::AbstractGroupNC, ECModel::AbstractEC)

Function to finalize the results of the Non Cooperative model after the execution Many of the variables are set to zero due to the absence of cooperation between users

Function to get the general parameters

Function to get the list of generators for a user

get_annotations(ECModel::AbstractEC)

Get annotations for Benders decomposition

get_group_type(ECModel::AbstractEC)

Returns the EC group type

get_subproblem_vars_by_user(var::Containers.DenseAxisArray{T}, u_name) where T <: VariableRef

Get variables related to the user u_name for a DenseAxisArray

get_subproblem_vars_by_user(var::Containers.SparseAxisArray{T}, u_name) where T <: VariableRef

Get variables related to the user u_name for a SparseAxisArray

get_user_set(ECModel::AbstractEC)

Returns the EC user set

Function to check whether an user has any asset

Function to check whether an user has an asset type

Function to check whether an user has an asset given its name

Function to know if a dictionary has a particular component

Auxiliary function to check if the key 'type' is available in the dictionary d, otherwise false

load!(output_file::AbstractString, ECModel::AbstractEC)

Loads the Energy Community model stored in the file specified by output_file and updates the relevant fields of ECModel. This function performs basic checks on the loaded data, verifying the existence of the necessary keys ("data", "userset", "grouptype", "results"), and restores the model components (such as data, users_data, and results) accordingly.

Function to get the market configuration

market_profile_by_user(ECModel::AbstractEC, u_name, profile_name)

Function to retrieve the market profile of each user, according to their market type (e.g. commercial, domestic, etc.)

Arguments

• ECModel: EC model object
• u_name: user name
• profile_name: profile name

Returns

It returns the vector of data corresponding to the profile of the user according to the market type

name(model::AbstractEC)

Return the name of the model.

name(model::ModelEC)

Return the name of the model.

objective_by_user(ECModel::AbstractEC; add_EC=true)

Returns the objective function by user; when add_EC is true, the EC is added to the user set

Function to return the objective function by user in the Aggregated Non Cooperative case

Function to return the objective function by user in the Cooperative case

Function to return the objective function by user in the NonCooperative case

Function to throw error for unformatted data

Function to parse a string value of a profile to load the corresponding dataframe

Function to parse a personalized processing to generate the data When profile_value is a dictionary, then the user is asking a custom processing of data by a function

Function to parse a string value of a profile to load the corresponding dataframe

Function to parse a string value of a profile to load the corresponding dataframe

Function to parse the peak power categories and tariff

plot_sankey(ECModel::AbstractEC, sank_data::Dict; label_size = 10)

Function to plot the Sankey diagram representing the energy flows across the energy community. This function can be used to plot the sankey diagram of already processed data sank_data.

Arguments

• ECModel::AbstractEC: Energy Community model
• sank_data::Dict: Dictionary containing the data to plot the Sankey diagram, in agreement to SankeyPlots.jl package

function plot_sankey(ECModel::AbstractEC; name_units=nothing, norm_value=nothing, market_color=palette(:rainbow)[2], community_color=palette(:rainbow)[5], users_colors=palette(:default), label_size=10)

Function to plot the Sankey diagram representing the energy flows across the energy community

Arguments

• ECModel::AbstractEC: Energy Community model
• name_units: (optional) Labels used for the sankey diagram with the following order: "Market buy", [users labels], "Community", "Market sell", [users labels]
• norm_value: (optional) Normalization value for the flows
• market_color: (optional) Color of the market
• community_color: (optional) Color of the community
• users_colors: (optional) Colors of the users
• label_size: (optional) Size of the labels in the Sankey diagram

prepare_summary(::AbstractGroupANC, ECModel::AbstractEC;
    user_set::Vector=Vector())

Save base excel file with a summary of the results for the Aggregated Non Cooperative case

prepare_summary(::AbstractGroupCO, ECModel::AbstractEC; user_set::Vector=Vector())

Save base excel file with a summary of the results for the Cooperative case

prepare_summary(::AbstractGroupNC, ECModel::AbstractEC, file_summary_path::AbstractString;
    user_set::Vector=Vector())

Prepare the dataframe lists to be saved in an excel file.

Arguments

• group_type::AbstractGroupNC: The type of group model
• ECModel::AbstractEC: The EC model to be built
• file_summary_path::AbstractString: The file path where to save the excel file
• user_set::AbstractVector: The user set to be considered

Returns

• output_list::Vector: The list of dataframes to be saved in the excel file

print_summary(ECModel::AbstractEC; kwargs...)

Function to print a summary of the results of the model. The function dispatches the execution to the appropriate function depending on the Aggregation type of the EC

print_summary(::AbstractGroupANC, ECModel::AbstractEC)

Function to print the main results of the model

print_summary(::AbstractGroupCO, ECModel::AbstractEC)

Function to print the main results of the model

print_summary(::AbstractGroupNC, ECModel::AbstractEC)

Function to print the main results of the model

Arguments

• group_type::AbstractGroupNC: The type of group model
• ECModel::AbstractEC: The EC model to be built

Function to get a specific profile

Function to get a specific profile

Function to get the profile dictionary

Function to read the input of the optimization model described as a yaml file

reset_user_set!(ECModel::AbstractEC)

Reset the EC user set to match the stored user_set of the ECModel data

save_summary(ECModel::AbstractEC, output_file::AbstractString; kwargs...)

Function to save a summary of the results of the model. The function dispatches the execution to the appropriate function depending on the Aggregation type of the EC

set_group_type!(ECModel::AbstractEC)

Sets the EC group type

set_least_profitable_profit!(ECModel::AbstractEC, profit_distribution)

Function to set the profit distribution of the least profitable problem.

Arguments

• ECModel::AbstractEC: Model of the community
• profit_distribution::AbstractDict: Profit distribution per user

Function to set the objective function of the model of the Aggregated-Non-Cooperative model

set_objective!(::AbstractGroupCO, ECModel::AbstractEC)

Set the objective for the cooperative approach

set_objective!(::AbstractGroupNC, ECModel::AbstractEC)

Function to set the objective function of the model of the Non-Cooperative model, which is to maximize the annual profits of all users.

Arguments

• group_type::AbstractGroupNC: The type of group model
• ECModel::AbstractEC: The EC model to be built

Returns

• ECModel::AbstractEC: The EC model with the objective set

set_user_set(ECModel::AbstractEC)

Sets the EC user set

split_financial_terms(ECModel::AbstractEC, profit_distribution=nothing)

Function to describe the cost term distributions for each user. Each entry that follows is DenseAxisArray for an economic parameter by user.

Arguments

• ECModel::AbstractEC: Energy Community model
• profit_distribution: (optional) DenseAxisArray with the profit distribution by user

Returns

The output value is a NamedTuple with the following elements:

• NPV: the NPV of each user given the final profit_distribution adjustment by game theory
• CAPEX: the annualized CAPEX
• OPEX: the annualized operating costs (yearly maintenance and yearly peak and energy grid charges)
• REP: the annualized replacement costs
• RV: the annualized recovery charges
• REWARD: the annualized reward distribution by user
• PEAK: the annualized peak costs
• EN_SELL: the annualized revenues from energy sales
• EN_BUY: the annualized costs from energy consumption and buying
• EN_NET: the annualized net energy costs

splityearlyfinancialterms(ECModel::AbstractEC, profitdistribution)

Function to describe the cost term distributions by all users for year. It returns major economic inputs summed across users and the community by year.

Arguments

• ECModel::AbstractEC: Energy Community model
• profit_distribution: (optional) DenseAxisArray with the profit distribution by user

Returns

The output value is a NamedTuple with the following elements:

• NPV: the NPV of each user given the final profit_distribution adjustment by game theory
• CAPEX: the CAPEX by year
• OPEX: the operating costs by year (yearly maintenance and yearly peak and energy grid charges)
• REP: the replacement costs by year
• RV: the recovery charges by year
• REWARD: the reward distribution by year
• PEAK: the peak costs by year
• EN_SELL: the revenues from energy sales by year
• EN_BUY: the costs from energy consumption and buying by year
• EN_NET: the net energy costs by year
• year_set: the list of years under consideration

to_least_profitable_coalition_callback(
    ECModel::AbstractEC,
    base_group::AbstractGroup;
    no_aggregator_group::AbstractGroup=GroupNC(),
    optimizer=nothing,
    raw_outputs=false,
    number_of_solutions=1,
    relax_combinatorial=false,
    use_notations=false,
    callback_solution=Dict(),
    branching_priorities=true,
    decompose_ANC=true,
    decompose_rel_tolerance=0.05,
    decompose_abs_tolerance=1e-2,
    kwargs...
)

Function that returns a callback function that, given as input a profit distribution scheme, returns the coalition that has the least benefit in remaining in the grand coalition. The returned function least_profitable_coalition_callback accepts an AbstractDict as argument that specifies the profit distribution by user that is used to compute the least benefit procedure.

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study. When the model is not cooperative an error is thrown.
• base_group::AbstractGroup: Base group with respect the benefit is calculated
• no_aggregator_group::AbstractGroup=GroupNC(): Type of aggregation group of the community when no aggregator is available
• optimizer::Optimizer=nothing: Optimizer to use
• raw_outputs::Bool=false: Flag to return raw outputs; see return section for more details
• number_of_solutions::Int=1: Number of solutions to return from each iteration; when number_of_solutions <= 0 all solutions are returned
• relax_combinatorial::Bool=false: Flag to relax the combinatorial part of the MILP model
• use_notations::Bool=false: Flag to use notations in the model
• callback_solution::Dict(): Dictionary of callbacks depending on the termination status of the optimization. Keys shall be of type JuMP.TerminationStatusCode, and outputs a function with as argument a ModelEC
• branching_priorities::Bool=true: Option to specify if add the branching priorities
• decompose_ANC::Bool=true: When True, if the noaggregatorgroup is ANC and, then the main optimization model is decomposed into two models: (a) when no Aggregator is in the coalition and (b) when the aggregator is in the coalition. In this case, (a) is optimized first and if the optimization is beyond a given threshold, the execution is terminated without optimizing (b). The threshold is provided as an optional input in the callback function returned by the function. Otherwise the optimization continues with (b).
• decompose_rel_tolerance=0.05: Relative tolerance of the decompose_ANC procedure
• decompose_abs_tolerance=1e-2: Absolute tolerance of the decompose_ANC procedure

Returns

• least_profitable_coalition_callback: Function that accepts as input an AbstractDict representing the benefit distribution by user
• ecm_copy: (when raw_outputs=true) ModelEC copy of the ECModel, used in the callback function

to_objective_callback_by_subgroup(ECModel::AbstractEC)

Function that returns a callback function that quantifies the objective of a given subgroup of users The returned function objective_func accepts as arguments an AbstractVector of users and returns the objective of the aggregation for any model

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study. When the model is not cooperative an error is thrown.

Returns

• objective_callback_by_subgroup: Function that accepts as input an AbstractVector (or Set) of users and returns as output the benefit of the specified community

to_objective_callback_by_subgroup(::AbstractGroupANC, ECModel::AbstractEC; base_model=nothing, kwargs...)

Function that returns a callback function that quantifies the objective of a given subgroup of users The returned function objective_func accepts as arguments an AbstractVector of users and returns the objective of the aggregation for Aggregated Non Cooperative models

Arguments

• group_type: The type of group model
• ECModel: EC Model of the EC to study. When the model is not cooperative an error is thrown.
• base_model: EC Model (optional). When provided, it represents the base model used to perform the calculations

Returns

It returns a function that accepts as input an AbstractVector (or Set) of users and returns as output the benefit of the specified community

to_objective_callback_by_subgroup(::AbstractGroupCO, ECModel::AbstractEC)

Function that returns a callback function that quantifies the objective of a given subgroup of users The returned function objective_func accepts as arguments an AbstractVector of users and returns the objective of the aggregation for Aggregated Cooperative models

Arguments

• group_type: The type of group model
• ECModel : Cooperative EC Model of the EC to study. When the model is not cooperative an error is thrown.
• no_aggregator_group (optional, default NonCooperative): EC group type when no aggregator is considered

Returns

It returns a function that accepts as input an AbstractVector (or Set) of users and returns as output the benefit of the specified community

to_objective_callback_by_subgroup(::AbstractGroupNC, ECModel::AbstractEC)

Function that returns a callback function that quantifies the objective of a given subgroup of users The returned function objective_func accepts as arguments an AbstractVector of users and returns the objective of the aggregation for Non Cooperative models

Arguments

• group_type: The type of group model
• ECModel : Cooperative EC Model of the EC to study. When the model is not cooperative an error is thrown.

Returns

It returns a function that accepts as input an AbstractVector (or Set) of users and returns as output the benefit of the specified community

to_utility_callback_by_subgroup(
    ECModel::AbstractEC, base_group_type::AbstractGroup;
    no_aggregator_group::AbstractGroup=GroupNC(),
    kwargs...
)

Function that returns a callback function that quantifies the benefit of a given subgroup of users The returned function utility_func accepts as arguments an AbstractVector of users and returns the benefit with respect to the base case of the users optimized independently

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study.
• base_group_type::AbstractGroup: Type of the base case to consider
• no_aggregator_group::AbstractGroup=GroupNC(): EC group type for when no aggregator is considered

Returns

• utility_callback_by_subgroup::Function: Function that accepts as input an AbstractVector (or Set) of users and returns as output the benefit of the specified community

Get the list of users

Function to get the users configuration

load(output_file::AbstractString, ECModel::AbstractEC)

Function to save the results and the model to the hard drive; ECModel is not modified. The function saves data, userset, grouptype and results of the ECModel in a dictionary and then saves the dictionary in the output_file.

save(output_file::AbstractString, ECModel::AbstractEC)

Function to save the results and the model to the hard drive. The function saves data, userset, grouptype and results of the ECModel in a dictionary and then saves the dictionary in the output_file.

objective_function(ECModel::AbstractEC)

Gets the objective function of the model

JuMP.objective_value(ECModel::AbstractEC)

Returns the objective value of the EC model

JuMP.optimize!(ECModel::AbstractEC)

Solve the optimization problem for the EC. It optimizes the model of the EC and stores the results in the results attribute of the ECModel.

JuMP.result_count(ECModel::AbstractEC)

Returns the result count of the JuMP model of the EC model

termination_status(ECModel::AbstractEC)

Calculates the optimization status of the model

Plots.plot(ECModel::ModelEC, output_plot_file::AbstractString="")

Function to plot the EC model

Plots.plot(::AbstractGroupANC, ECModel::AbstractEC, output_plot_file::AbstractString;
user_set::AbstractVector = Vector(), line_width = 2.0)

Function to plot the results of the Aggregated non cooperative configuration

Plots.plot(::AbstractGroupCO, ECModel::AbstractEC, output_plot_file::AbstractString;
user_set::AbstractVector = Vector(), line_width = 2.0)

Function to plot the results of the Cooperative EC

Plots.plot(::AbstractGroupNC, ECModel::AbstractEC, output_plot_file::AbstractString;
    user_set::Vector=Vector(), line_width=2.0)

Function to plot the results of the user model

Arguments

• group_type::AbstractGroupNC: The type of group model
• ECModel::AbstractEC: The EC model to be built
• output_plot_file::AbstractString: The file path where to save the plots
• user_set::Vector: The user set to plot
• line_width::Float64: The width of the lines in the plot

@enum ASSET_TYPE

Enumeration type to specify the type of the assets. Implemented values:

• LOAD: load components
• REN: renewable assets
• BATT: battery components
• CONV: battery converters
• THER: thermal generators

AbstractEC

Abstract type for an EnergyCommunity model.

AbstractGroup

Abstract type for the group model; it is the parent of the three types of group models: Cooperative, Non-Cooperative, and Aggregated Non-Cooperative.

GroupANC <: AbstractGroupANC

Concrete type for the Aggregated Non-Cooperative group model.

GroupCO <: AbstractGroupCO

Concrete type for the Cooperative group model.

GroupNC <: AbstractGroupNC

Concrete type for the Non-Cooperative group model.

ModelEC <: AbstractEC

Concrete type for an EnergyCommunity model.

Attributes

• data::Dict: All data
• gen_data::Dict: general data
• market_data::Dict: market data
• users_data::Dict: users data
• group_type: aggregation type of model
• user_set::Vector: desired user set
• model::Model: JuMP model
• optimizer: optimizer of the JuMP model
• results::Dict: results of the model in Dictionary format

ModelEC(model_copy::ModelEC, group_type=nothing, optimizer=nothing, user_set=nothing)

Copy constructor; it copies the data from model_copy and changes the group type, optimizer, and user set if specified.

Arguments

• model_copy::ModelEC: model to copy
• group_type=nothing: aggregation type of model; default is the same as model_copy
• optimizer=nothing: optimizer of the JuMP model; default is the same as model_copy
• user_set=nothing: desired user set; default is the same as model_copy

ModelEC(data::Dict=ZERO_DD, group_type=GroupNC(), optimizer=nothing, user_set::Vector=Vector())

Constructor of a ModelEC.

Arguments

• data::Dict=ZERO_DD: All data; a dictionary with the keys "general", "users", and "market"
• group_type: aggregation type of model
• optimizer: optimizer of the JuMP model
• user_set::Vector: desired user set

ModelEC(file_name::AbstractString, group_type, optimizer=nothing)

Load EnergyCommunity model from disk

Arguments

• file_name::AbstractString: name of the file to load the data
• group_type: aggregation type of model
• optimizer: optimizer of the JuMP model

TheoryOfGames.EnumMode(ECModel::AbstractEC, base_group::AbstractGroup; verbose::Bool=true, kwargs...)

Function to create the EnumMode item for the TheoryOfGames.jl package.

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study.
• base_group::AbstractGroup: Type of the base case to consider
• verbose::Bool=true: Flag to print the results
• kwargs...: Additional arguments

Returns

• enum_mode: TheoryOfGames.EnumMode object

TheoryOfGames.IterMode(
    ECModel::AbstractEC,
    base_group_type::AbstractGroup; 
    no_aggregator_type::AbstractGroup=GroupNC(),
    optimizer=nothing,
    number_of_solutions=0,
    use_notations=false,
    decompose_ANC=true,
    decompose_abs_tolerance=1e-4,
    decompose_rel_tolerance=1e-4,
    kwargs...
)

Function to create the IterMode item for the TheoryOfGames.jl package

Arguments

• ECModel::AbstractEC: Cooperative EC Model of the EC to study.
• base_group_type::AbstractGroup: Type of the base case to consider
• no_aggregator_type::AbstractGroup=GroupNC(): Type of the base case to consider when no aggregator is available
• optimizer::Optimizer=nothing: Optimizer to use
• number_of_solutions::Int=0: Number of solutions to return from each iteration; when number_of_solutions <= 0 all solutions are returned
• use_notations::Bool=false: Flag to use notations in the model
• decompose_ANC::Bool=true: When True, if the noaggregatorgroup is ANC and, then the main optimization model is decomposed into two models. See to_least_profitable_coalition_callback for more details
• decompose_rel_tolerance=0.05: Relative tolerance of the decompose_ANC procedure
• decompose_abs_tolerance=1e-2: Absolute tolerance of the decompose_ANC procedure
• kwargs...: Additional arguments

Returns

• iter_mode: TheoryOfGames.IterMode object