Code documentation¶

Util functions¶

Module data_parser¶

This module defines all functions to convert formats between EPA and MVS - Define similar parameters mapping between the EPA and MVS in MAP_EPA_MVS and MAP_MVS_EPA - Define which fields are expected in asset list of EPA for various assets’ groups in EPA_ASSET_KEYS - Convert MVS to EPA - Convert EPA to MVS

multi_vector_simulator.utils.data_parser.convert_epa_params_to_mvs(epa_dict)¶

Convert the EPA output parameters to MVS input parameters

Parameters: epa_dict (dict) – parameters from EPA user interface
Returns: dict_values – MVS json file, generated from EPA inputs, to be provided as MVS input
Return type: dict

Notes

For simulation_settings:
- parameter TIMESTEP is parsed as unit-value pair
- OUTPUT_LP_FILE always False
For project_data: parameter SCENARIO_DESCRIPTION is defined as placeholder string.
fix_cost is not required, default value will be set if it is not provided.
For missing asset group CONSTRAINTS following parameters are added:
- MINIMAL_RENEWABLE_FACTOR: 0
- MAXIMUM_EMISSIONS: None
- MINIMAL_DEGREE_OF_AUTONOMY: 0
ENERGY_STORAGE assets:
- Optimize cap written to main asset and removed from subassets
- Units defined automatically (assumed: electricity system)
- SOC_INITIAL: None
- THERM_LOSSES_REL: 0
- THERM_LOSSES_ABS: 0
If TIMESERIES parameter in asset dictionary: Redefine unit, value and label.
ENERGY_PROVIDERS:
- Auto-define unit as kWh(el)
- INFLOW_DIRECTION=OUTFLOW_DIRECTION
- Default value for EMISSION_FACTOR added
ENERGY_CONSUMPTION:
- DSM is False
- DISPATCHABILITY is FALSE
ENERGY_PRODUCTION:
- Default value for EMISSION_FACTOR added
- DISPATCHABILITY is always False, as no dispatchable fuel assets possible right now. Must be tackeld by EPA.

multi_vector_simulator.utils.data_parser.convert_mvs_params_to_epa(mvs_dict, verbatim=False)¶

Convert the MVS output parameters to EPA format

Parameters: mvs_dict (dict) – output parameters from MVS
Returns: epa_dict – epa parameters
Return type: dict

Helper functions¶

Util functions that are useful throughout the MVS

Including: - find_valvue_by_key(): Finds value of a key in a nested dictionary.

multi_vector_simulator.utils.helpers.find_value_by_key(data, target, result=None)¶

Finds value of a key in a nested dictionary.

Parameters

data (dict) – Dict to be searched for target key
target (str) – Key for which the value should be found in data
result (None, value or list) – Only provided if function loops in itself

Returns

value if the key is only once in data
list of values if it appears multiple times.

multi_vector_simulator.utils.helpers.translates_epa_strings_to_mvs_readable(folder_name, file_name)¶

This function translates the json file generated by the EPA to a file readable by the MVS. This is necessary as there are some parameter names whose string representative differs in both tools.

Parameters

folder_name (path) – Path to the folder with the json file
file_name (json file name with extension) – Json to be converted

Returns

Stores converted json file to current dict
Usage – import multi_vector_simulator.utils.helpers as helpers helpers.translates_epa_strings_to_mvs_readable(“./epa_benchmark”, “epa_benchmark.json-original”)

Initialization¶

Module A0 - Initialization¶

Module A0_initialization defines functions to parse user inputs to the MVS simulation.

Display welcome message with current version number
Parse command line arguments and set default values for MVS parameters if not provided
Check that all necessary files and folder exist
Create output directory
Define screen logging depth

Usage from root of repository:

python mvs_tool.py [-h] [-i [PATH_INPUT_FOLDER]] [-ext [{json,csv}]] [-o [PATH_OUTPUT_FOLDER]]
[-log [{debug,info,error,warning}]] [-f [OVERWRITE]] [-pdf [PDF_REPORT]] [-png [SAVE_PNG]]

Usage when multi-vector-simulator is installed as a package:

mvs_tool [-h] [-i [PATH_INPUT_FOLDER]] [-ext [{json,csv}]] [-o [PATH_OUTPUT_FOLDER]]
[-log [{debug,info,error,warning}]] [-f [OVERWRITE]] [-pdf [PDF_REPORT]] [-png [SAVE_PNG]]

Process MVS arguments

optional arguments:

-h, --help: show this help message and exit

-i [PATH_INPUT_FOLDER]: path to the input folder
-ext [{json,csv}]: type (json or csv) of the input files (default: ‘json’)
-o [PATH_OUTPUT_FOLDER]: path to the output folder for the simulation’s results
-log [{debug,info,error,warning}]: level of logging in the console
-f [OVERWRITE]: overwrite the output folder if True (default: False)
-pdf [PDF_REPORT]: generate a pdf report of the simulation if True (default: False)
-png [SAVE_PNG]: generate png figures of the simulation in the output_folder if True (default: False)

multi_vector_simulator.A0_initialization.check_input_folder(path_input_folder, input_type)¶

Enforces the rules for the input folder and files

There should be a single json file for config (described under JSON_FNAME) in case input_type is equal to JSON_EXT. There should be a folder with csv files (name of folder given by CSV_ELEMENTS) in case input_type is equal to CSV_EXT.

Parameters

path_input_folder – path to input folder
input_type – of of JSON_EXT or CSV_EXT

Returns

the json filename which will be used as input of the simulation

multi_vector_simulator.A0_initialization.check_output_folder(path_input_folder, path_output_folder, overwrite)¶

Enforces the rules for the output folder

An error is raised if the path_output_folder already exists, unless overwrite is set to True. The path_output_folder is created if not existing and the content of path_input_folder is copied in a folder named INPUTS_COPY.

Parameters

path_input_folder – path to input folder
path_output_folder – path to output folder
overwrite – boolean indicating what to do if the output folder exists already

Returns

the path to the folder stored in the output folder as copy of the input folder

multi_vector_simulator.A0_initialization.mvs_arg_parser()¶

Create a command line argument parser for MVS

Usage from root of repository:

python mvs_tool.py [-h] [-i [PATH_INPUT_FOLDER]] [-ext [{json,csv}]] [-o [PATH_OUTPUT_FOLDER]]
[-log [{debug,info,error,warning}]] [-f [OVERWRITE]] [-pdf [PDF_REPORT]] [-png [SAVE_PNG]]
[--version]

Usage when multi-vector-simulator is installed as a package:

mvs_tool [-h] [-i [PATH_INPUT_FOLDER]] [-ext [{json,csv}]] [-o [PATH_OUTPUT_FOLDER]]
[-log [{debug,info,error,warning}]] [-f [OVERWRITE]] [-pdf [PDF_REPORT]] [-png [SAVE_PNG]]
[--version]

Process MVS arguments

optional arguments:

-h, --help: show this help message and exit

-i [PATH_INPUT_FOLDER]: path to the input folder
-ext [{json,csv}]: type (json or csv) of the input files (default: ‘json’)
-o [PATH_OUTPUT_FOLDER]: path to the output folder for the simulation’s results
-log [{debug,info,error,warning}]: level of logging in the console
-f [OVERWRITE]: overwrite the output folder if True (default: False)
-pdf [PDF_REPORT]: generate a pdf report of the simulation if True (default: False)
-png [SAVE_PNG]: generate png figures of the simulation in the output_folder if True (default: False)

--version: show program’s version number and exit

Returns: parser

multi_vector_simulator.A0_initialization.process_user_arguments(path_input_folder=None, input_type=None, path_output_folder=None, overwrite=None, pdf_report=None, display_output=None, save_png=None, lp_file_output=False, welcome_text=None)¶

Process user command from terminal inputs. If inputs provided as arguments of the function, they will overwrite the command line arguments.

Parameters

path_input_folder – Describes path to inputs folder (command line “-i”)
input_type – Describes type of input to expect (command line “-ext”)
path_output_folder – Describes path to folder to be used for terminal output (command line “-o”) Must not exist before
overwrite – (Optional) Can force tool to replace existing output folder (command line “-f”)
pdf_report – (Optional) Can generate an automatic pdf report of the simulation’s results (Command line “-pdf”)
save_png – (Optional) Can generate png figures with the simulation’s results (Command line “-png”)
display_output – (Optional) Determines which messages are used for terminal output (command line “-log”) Allowed values are “debug”: All logging messages, “info”: All informative messages and warnings (default), “warning”: All warnings, “error”: Only errors,
lp_file_output – Save linear equation system generated as lp file
welcome_text – Text to be displayed

Returns

a dict with these arguments as keys (except welcome_text which is replaced by label)

multi_vector_simulator.A0_initialization.report_arg_parser()¶

Create a command line argument parser for MVS

Usage when multi-vector-simulator is installed as a package:

mvs_report [-h] [-i [PATH_SIM_OUTPUT]] [-o [REPORT_PATH]] [-pdf]

Process mvs report command line arguments

optional arguments:

-h, --help: show this help message and exit

-pdf [PRINT_REPORT]: print the report as pdf (default: False)
-i [OUTPUT_FOLDER]: path to the simulation result json file ‘json_with_results.json’
-o [REPORT_PATH]: path to save the pdf report

Returns: parser

Module A1 - Csv to json¶

Convert csv files to json file as input for the simulation.

The default input csv files are stored in “/inputs/elements/csv”. Otherwise their path is provided by the user.

The user can change parameters of the simulation of of the energy system in the csv files.

Storage: The “energyStorage.csv” contains information about all storages. For each storage there needs to be another file named exactly after each storage-column in the “energyStorage.csv” file. For the default file this is “storage_01”, “storage_02” etc. Please stick to this convention.

The function “create_input_json()” reads all csv files that are stored in the given input folder (input_directory) and creates one json input file for mvs_tool.

Functions of this module (that need to be tested) - read all necessary input files (REQUIRED_CSV_FILES) from input folder - display error message if CSV_FNAME already in input folder - read all parameters in from csv files - parse parameter that is given as a timeseries with input file name and header - parse parameter that is given as a list

check that parameter that is given as a list results and subsequent other parameters to be given as list e.g. if we have two output flows in conversion assets there should be two efficiencies to operational costs (this is not implemented in code yet)
only necessary parameters should be transferred to json dict, error message with additonal parameters
parse data from csv according to intended types - string, boolean, float, int, dict, list!

multi_vector_simulator.A1_csv_to_json.add_storage_components(storage_filename, input_directory, storage_label)¶

Creates json dict from storage csv.

Loads the csv of a the specific storage listed as column in “energyStorage.csv”, checks for complete set of parameters, adds a label and creates a json dictionary.

Parameters

storage_filename (str) – file name excl. extension, given by the parameter ‘file_name` in “energyStorage.csv
input_directory (str) – path to the input directory where storage_filename is located
storage_label (str) – Label of storage

Notes

Tested with: - test_add_storage_components_label_correctly_added()

Returns: dictionary containing the storage parameters
Return type: dict

multi_vector_simulator.A1_csv_to_json.check_storage_file_is_csv(storage_file)¶

Checks that the storage file name defined in energyStorage.csv has ending .csv.

Parameters

storage_file (str) – Defined storage file name

Returns

If test fails (MissingCsvEndingError(ValueError), else:)
storage_file (str) – Storage file name without ending ‘.csv’

multi_vector_simulator.A1_csv_to_json.conversion(value, asset_dict, row, param, asset, filename='')¶

This function converts the input given in the csv to the dict used in the MVS.

When using json files, they are already provided parsed like this functions output.

Parameters

value (Misc.) – Value to be parsed
asset_dict (dict) – Dict of asset that is to be filled with data
row –
param (str) – Parameter that is currently parsed
asset –
filename –

multi_vector_simulator.A1_csv_to_json.create_input_json(input_directory, pass_back=True)¶

Convert csv files to json file as input for the simulation.

Looks at all csv-files in input_directory and compile the information they contain into a json file. The json file is then saved within the input_directory with the filename CSV_FNAME. While reading the csv files, it is checked, whether all required parameters for each component are provided. Missing parameters will return a warning message.

Parameters

input_directory – path of the directory where the input csv files can be found
str – path of the directory where the input csv files can be found
pass_back – if True the final json dict is returned. Otherwise it is only saved
bool – if True the final json dict is returned. Otherwise it is only saved
optional – if True the final json dict is returned. Otherwise it is only saved

Returns

Return type

None or dict

multi_vector_simulator.A1_csv_to_json.create_json_from_csv(input_directory, filename, parameters=None, asset_is_a_storage=False)¶

One csv file is loaded and it’s parameters are checked. The csv file is then converted to a dictionary; the name of the csv file is used as the main key of the dictionary. Exceptions are made for the files [“economic_data”, “project”, “project_data”, “simulation_settings”, “constraints”], here no main key is added. Another exception is made for the file “energyStorage”. When this file is processed, the according “storage” files (names of the “storage” columns in “energyStorage” are called and added to the energyStorage Dictionary.

Parameters

input_directory (str) – path of the directory where the input csv files can be found
filename (str) – name of the input file that is transformed into a json, without extension
parameters (list) – List of parameters names that are required
asset_is_a_storage (bool) – default value is False. If the function is called by add_storage_components() the parameter is set to True

Returns

the converted dictionary

Return type

dict

Notes

Tested with: - test_default_values_storage_without_thermal_losses() - test_default_values_storage_with_thermal_losses()

Data input¶

Module B0 - Data input json¶

multi_vector_simulator.B0_data_input_json.convert_from_json_to_special_types(a_dict, prev_key=None, time_index=None)¶

Convert the field values of the mvs result json file which are not simple types.

The function is recursive to explore all nested levels

Parameters

a_dict (variable) – In the recursion, this is either a dict (moving down one nesting level) or a field value
prev_key (str) – The previous key of the dict in the recursive loop

Returns

The original dictionary, with the serialized instances of pandas.Series,
pandas.DatetimeIndex, pandas.DataFrame, numpy.array converted back to their original form

multi_vector_simulator.B0_data_input_json.convert_from_special_types_to_json(o)¶

This converts all data stored in dict_values that is not compatible with the json format to a format that is compatible.

Parameters: o – Any type. Object to be converted to json-storable value.
Returns: json-storable value.
Return type: type

multi_vector_simulator.B0_data_input_json.load_json(path_input_file, path_input_folder=None, path_output_folder=None, move_copy=False, flag_missing_values=True, set_default_values=False)¶

Opens and reads json input file and parses it to dict of input parameters.

Parameters

path_input_file (str) – The path to the json file created from csv files
path_input_folder (str, optional) – The path to the directory where the input CSVs/JSON files are located. Default: ‘inputs/’.
path_output_folder (str, optional) – The path to the directory where the results of the simulation such as the plots, time series, results JSON files are saved by MVS E-Lands. Default: ‘MVS_outputs/’
move_copy (bool, optional) – if this is set to True, the path_input_file will be moved to the path_output_folder Default: False
flag_missing_values (bool) – if True, raise MissingParameterError for each missing required parameter
set_default_values (bool) – if True, set the default value of a missing required parameter which is listed in KNOWN_EXTRA_PARAMETERS

Returns

Return type

dict of all input parameters of the MVS E-Lands simulation

multi_vector_simulator.B0_data_input_json.retrieve_date_time_info(simulation_settings)¶

Updates simulation settings by all time-related parameters. - START_DATE - END_DATE - TIME_INDEX - PERIODS

Parameters: simulation_settings (dict) – Simulation parameters of the input data
Returns
Return type: Update simulation_settings by start date, end date, timeindex, and number of simulation periods

Notes

Function tested with test_retrieve_datetimeindex_for_simulation()

Data pre-processing and validity checks¶

Module C0 - Data processing¶

Module C0 prepares the data read from csv or json for simulation, ie. pre-processes it. - Verify input values with C1 - Identify energyVectors and write them to project_data/sectors - Create an excess sink for each bus - Process start_date/simulation_duration to pd.datatimeindex (future: Also consider timesteplenghts) - Add economic parameters to json with C2 - Calculate “simulation annuity” used in oemof model - Add demand sinks to energyVectors (this should actually be changed and demand sinks should be added to bus relative to input_direction, also see issue #179) - Translate input_directions/output_directions to bus names - Add missing cost data to automatically generated objects (eg. DSO transformers) - Read timeseries of assets and store into json (differ between one-column csv, multi-column csv) - Read timeseries for parameter of an asset, eg. efficiency - Parse list of inputs/outputs, eg. for chp - Define dso sinks, sources, transformer stations (this will be changed due to bug #119), also for peak demand pricing - Add a source if a conversion object is connected to a new input_direction (bug #186) - Define all necessary energyBusses and add all assets that are connected to them specifically with asset name and label - Multiply maximumCap of non-dispatchable sources by max(timeseries(kWh/kWp)) as the maximumCap is limiting the flow but we want to limit the installed capacity (see issue #446)

multi_vector_simulator.C0_data_processing.add_a_transformer_for_each_peak_demand_pricing_period(dict_values, dict_dso, dict_availability_timeseries)¶

Adds transformers that are supposed to model the peak_demand_pricing periods for each period. This is changed compared to MVS 0.3.0, as there a peak demand pricing period was added by adding a source, not a transformer.

Parameters

dict_values (dict) – dict with all simulation parameters
dict_dso (dict) – dict with all info on the specific dso at hand
dict_availability_timeseries (dict) – dict with all availability timeseries for each period

Returns

list_of_dso_energyConversion_assets (list) – List of names of newly added energy conversion assets,
Updated dict_values with a transformer for each peak demand pricing period

Notes

Tested by: - C0.test_add_a_transformer_for_each_peak_demand_pricing_period_1_period - C0.test_add_a_transformer_for_each_peak_demand_pricing_period_2_periods

multi_vector_simulator.C0_data_processing.add_asset_to_asset_dict_for_each_flow_direction(dict_values, dict_asset, asset_key)¶

Add asset to the asset dict of the busses connected to the INPUT_DIRECTION and OUTPUT_DIRECTION of the asset.

Parameters

dict_values (dict) – All simulation information
dict_asset (dict) – All information of the current asset
asset_key (str) – Key that calls the dict_asset from dict_values[asset_group][key]

Returns

Return type

Updated dict_values, with dict_values[ENERGY_BUSSES] now including asset dictionaries for each asset connected to a bus.

Notes

Tested with: - C0.test_add_asset_to_asset_dict_for_each_flow_direction()

multi_vector_simulator.C0_data_processing.add_asset_to_asset_dict_of_bus(bus, dict_values, asset_key, asset_label)¶

Adds asset key and label to a bus defined by energyBusses.csv Sends an error message if the bus was not included in energyBusses.csv

Parameters

dict_values (dict) – Dict of all simulation parameters
bus (str) – A bus label
asset_key (str) – Key with with an dict_asset would be called from dict_values[groups][key]
asset_label (str) – Label of the asset

Returns

Updated dict_values[ENERGY_BUSSES] by adding an asset to the busses` ASSET DICT
EnergyBusses now has following keys (LABEL, ENERGY_VECTOR, ASSET_DICT)

Notes

Tested with: - C0.test_add_asset_to_asset_dict_of_bus() - C0.test_add_asset_to_asset_dict_of_bus_ValueError()

multi_vector_simulator.C0_data_processing.add_assets_to_asset_dict_of_connected_busses(dict_values)¶

This function adds the assets of the different asset groups to the asset dict of ENERGY_BUSSES. The asset groups are: ENERGY_CONVERSION, ENERGY_PRODUCTION, ENERGY_CONSUMPTION, ENERGY_PROVIDERS, ENERGY_STORAGE

Parameters: dict_values (dict) – Dictionary with all simulation information
Returns
Return type: Extends dict_values[ENERGY_BUSSES] by an asset_dict that includes all connected assets.

Notes

Tested with: - C0.test_add_assets_to_asset_dict_of_connected_busses()

multi_vector_simulator.C0_data_processing.add_economic_parameters(economic_parameters)¶

Update economic parameters with annuity factor and CRF

Parameters: economic_parameters (dict) – Economic parameters of the simulation
Returns
Return type: Updated economic parameters

Notes

Function tested with test_add_economic_parameters()

multi_vector_simulator.C0_data_processing.add_version_number_used(simulation_settings)¶

Add version number to simulation settings

Parameters

simulation_settings (dict) – Dict of simulation settings

Returns

Updated dict simulation_settings with VERSION_NUM equal to local version number.
This version number will be added to the json output files.
The automatic report generated in F0 references the version number and date on its own accord.

multi_vector_simulator.C0_data_processing.all(dict_values)¶

Function executing all pre-processing steps necessary :param dict_values All input data in dict format

:return Pre-processed dictionary with all input parameters

multi_vector_simulator.C0_data_processing.apply_function_to_single_or_list(function, parameter, **kwargs)¶

Applies function to a paramter or to a list of parameters and returns resut

Parameters

function (func) – Function to be applied to a parameter
parameter (float/str/boolean or list) – Parameter, either float/str/boolean or list to be evaluated
kwargs – Miscellaneous arguments for function to be called

Returns

Return type

Processed parameter (single) or list of processed para<meters

multi_vector_simulator.C0_data_processing.change_sign_of_feedin_tariff(dict_feedin_tariff, dso)¶

Change the sign of the feed-in tariff. Additionally, prints a logging.warning in case of the feed-in tariff is entered as negative value in ‘energyProviders.csv’.

#todo This only works if the feedin tariff is not defined as a timeseries :param dict_feedin_tariff: Dict of feedin tariff with Unit-value pair :type dict_feedin_tariff: dict :param dso: Name of the energy provider :type dso: str

Returns: dict_feedin_tariff – Dict of feedin tariff, to be used as input to C0.define_sink
Return type: dict

Notes

Tested with: - C0.test_change_sign_of_feedin_tariff_positive_value() - C0.test_change_sign_of_feedin_tariff_negative_value() - C0.test_change_sign_of_feedin_tariff_zero()

multi_vector_simulator.C0_data_processing.compute_timeseries_properties(dict_asset)¶

Compute peak, aggregation, average and normalize timeseries

Parameters

dict_asset (dict) – dict of all asset parameters, must contain TIMESERIES key

Returns

None
Add TIMESERIES_PEAK, TIMESERIES_TOTAL, TIMESERIES_AVERAGE and TIMESERIES_NORMALIZED
to dict_asset

Notes

Function tested with - C0.test_compute_timeseries_properties_TIMESERIES_in_dict_asset() - C0.test_compute_timeseries_properties_TIMESERIES_not_in_dict_asset()

multi_vector_simulator.C0_data_processing.define_auxiliary_assets_of_energy_providers(dict_values, dso)¶

Defines all sinks and sources that need to be added to model the transformer using assets of energyConsumption, energyProduction and energyConversion.

Parameters

dict_values –
dso –

Returns

Return type

Updated dict_values

Notes

This function is tested with following pytests: - C0.test_define_auxiliary_assets_of_energy_providers() - C0.test_determine_months_in_a_peak_demand_pricing_period_not_valid() - C0.test_determine_months_in_a_peak_demand_pricing_period_valid() - C0.test_define_availability_of_peak_demand_pricing_assets_yearly() - C0.test_define_availability_of_peak_demand_pricing_assets_monthly() - C0.test_define_availability_of_peak_demand_pricing_assets_quarterly() - C0.test_add_a_transformer_for_each_peak_demand_pricing_period_1_period() - C0.test_add_a_transformer_for_each_peak_demand_pricing_period_2_periods() - C0.test_define_transformer_for_peak_demand_pricing() - C0.test_define_source() - C0.test_define_source_exception_unknown_bus() - C0.test_define_source_timeseries_not_None() - C0.test_define_source_price_not_None_but_with_scalar_value() - C0.test_define_sink() -> incomplete - C0.test_change_sign_of_feedin_tariff_positive_value() - C0.test_change_sign_of_feedin_tariff_negative_value() - C0.test_change_sign_of_feedin_tariff_zero()

multi_vector_simulator.C0_data_processing.define_availability_of_peak_demand_pricing_assets(dict_values, number_of_pricing_periods, months_in_a_period)¶

Determined the availability timeseries for the later to be defined dso assets for taking into account the peak demand pricing periods.

Parameters

dict_values (dict) – All simulation inputs
number_of_pricing_periods (int) – Number of pricing periods in a year. Valid: 1,2,3,4,6,12
months_in_a_period (int) – Duration of a period

Returns

dict_availability_timeseries – Dict with all availability timeseries for each period

Return type

dict

multi_vector_simulator.C0_data_processing.define_energy_vectors_from_busses(dict_values)¶

Identifies all energyVectors used in the energy system by looking at the defined energyBusses. The EnergyVectors later will be used to distribute costs and KPI amongst the sectors

Parameters: dict_values (dict) – All input data in dict format
Returns
Return type: Update dict[PROJECT_DATA] by included energyVectors (LES_ENERGY_VECTOR_S)

Notes

Function tested with - C1.test_define_energy_vectors_from_busses

multi_vector_simulator.C0_data_processing.define_excess_sinks(dict_values)¶

Define energy excess sinks for each bus

Parameters: dict_values (dict) – All simulation parameters
Returns
Return type: Updates dict_values

multi_vector_simulator.C0_data_processing.define_missing_cost_data(dict_values, dict_asset)¶

Parameters

dict_values –
dict_asset –

Returns

multi_vector_simulator.C0_data_processing.define_sink(dict_values, asset_key, price, inflow_direction, energy_vector, **kwargs)¶

This automatically defines a sink for an oemof-sink object. The sinks are added to the energyConsumption assets.

Parameters

dict_values (dict) – All information of the simulation
asset_key (str) – label of the asset to be generated
price (float) – Price of dispatch of the asset
inflow_direction (str) – Direction from which energy is provided to the sink
kwargs (Misc) – Common parameters: -

Returns

Updates dict_values[ENERGY_BUSSES] if outflow_direction not in it
Updates dict_values[ENERGY_CONSUMPTION] with a new sink

Notes

Examples: - Used to define excess sinks for all energyBusses - Used to define feed-in sink for each DSO

The pytests for this function are not complete. It is started with: - C0.test_define_sink() and only the assertion messages are missing

multi_vector_simulator.C0_data_processing.define_source(dict_values, asset_key, outflow_direction, energy_vector, emission_factor, price=None, timeseries=None)¶

Defines a source with default input values. If kwargs are given, the default values are overwritten.

Parameters

dict_values (dict) – Dictionary to which source should be added, with all simulation parameters
asset_key (str) – key under which the asset is stored in the asset group
energy_vector (str) – Energy vector the new asset should belong to
emission_factor (dict) – Dict with a unit-value pair of the emission factor of the new asset
price (dict) – Dict with a unit-value pair of the dispatch price of the source. The value can also be defined though FILENAME and HEADER, making the value of the price a timeseries. Default: None
timeseries (pd.Dataframe) – Timeseries defining the availability of the source. Currently not used. Default: None

Returns

Updates dict_values[ENERGY_BUSSES] if outflow_direction not in it
Standard source defined as

Notes

The pytests for this function are not complete. It is started with: - C0.test_define_source() - C0.test_define_source_exception_unknown_bus() - C0.test_define_source_timeseries_not_None() - C0.test_define_source_price_not_None_but_with_scalar_value() Missing: - C0.test_define_source_price_not_None_but_timeseries(), ie. value defined by FILENAME and HEADER

multi_vector_simulator.C0_data_processing.define_transformer_for_peak_demand_pricing(dict_values, dict_dso, transformer_name, timeseries_availability)¶

Defines a transformer for peak demand pricing in energyConverion

Parameters

dict_values (dict) – All simulation parameters
dict_dso (dict) – All values connected to the DSO
transformer_name (str) – label of the transformer to be added
timeseries_availability (pd.Series) – Timeseries of transformer availability. Introduced to cover peak demand pricing.

Returns

Return type

Updated dict_values with newly added transformer asset in the energyConversion asset group.

multi_vector_simulator.C0_data_processing.determine_dispatch_price(dict_values, price, source)¶

This function needs to be re-evaluated.

Parameters

dict_values –
price –
source –

multi_vector_simulator.C0_data_processing.determine_months_in_a_peak_demand_pricing_period(number_of_pricing_periods, simulation_period_lenght)¶

Check if the number of peak demand pricing periods is valid. Warns user that in case the number of periods exceeds 1 but the simulation time is not a year, there could be an unexpected number of timeseries considered. Raises error if number of peak demand pricing periods is not valid.

Parameters

number_of_pricing_periods (int) – Defined in csv, is number of pricing periods within a year
simulation_period_lenght (int) – Defined in csv, is number of days of the simulation

Returns

months_in_a_period – Number of months that make a period, will be used to determine availability of dso assets

Return type

float

multi_vector_simulator.C0_data_processing.energyConsumption(dict_values, group)¶

Parameters

dict_values –
group –

Returns

multi_vector_simulator.C0_data_processing.energyConversion(dict_values, group)¶

Add lifetime capex (incl. replacement costs), calculate annuity (incl. om), and simulation annuity to each asset

Parameters

dict_values –
group –

Returns

multi_vector_simulator.C0_data_processing.energyProduction(dict_values, group)¶

Parameters

dict_values –
group –

Returns

multi_vector_simulator.C0_data_processing.energyProviders(dict_values, group)¶

Parameters

dict_values –
group –

Returns

multi_vector_simulator.C0_data_processing.energyStorage(dict_values, group)¶

Parameters

dict_values –
group –

Returns

multi_vector_simulator.C0_data_processing.evaluate_lifetime_costs(settings, economic_data, dict_asset)¶

Evaluates specific costs of an asset over the project lifetime. This includes: - LIFETIME_PRICE_DISPATCH (C2.determine_lifetime_price_dispatch) - LIFETIME_SPECIFIC_COST - LIFETIME_SPECIFIC_COST_OM - ANNUITY_SPECIFIC_INVESTMENT_AND_OM - SIMULATION_ANNUITY

The DEVELOPMENT_COSTS are not processed here, as they are not necessary for the optimization.

Parameters

settings (dict) – dict of simulation settings, including: - EVALUATED_PERIOD
economic_data (dict) – dict of economic data of the simulation, including - project duration (PROJECT_DURATION) - discount factor (DISCOUNTFACTOR) - tax (TAX) - CRF - ANNUITY_FACTOR
dict_asset (dict) – dict of all asset parameters, including - SPECIFIC_COSTS - SPECIFIC_COSTS_OM - LIFETIME

Returns

Updates asset dict with
- LIFETIME_PRICE_DISPATCH (C2.determine_lifetime_price_dispatch)
- LIFETIME_SPECIFIC_COST
- LIFETIME_SPECIFIC_COST_OM
- ANNUITY_SPECIFIC_INVESTMENT_AND_OM
- SIMULATION_ANNUITY
- SPECIFIC_REPLACEMENT_COSTS_INSTALLED
- SPECIFIC_REPLACEMENT_COSTS_OPTIMIZED

Notes

Tested with: - test_evaluate_lifetime_costs_adds_all_parameters() - Test_Economic_KPI.test_benchmark_Economic_KPI_C2_E2()

multi_vector_simulator.C0_data_processing.get_timeseries_multiple_flows(settings, dict_asset, file_name, header)¶

Parameters

dict_asset –
of the asset (dictionary) –
file_name –
of the file to read the time series (name) –
header –
of the column where the timeseries is provided (name) –

multi_vector_simulator.C0_data_processing.process_all_assets(dict_values)¶

defines dict_values[‘energyBusses’] for later reference

Processes all assets of the energy system by evaluating them, performing economic pre-calculations and validity checks.

Parameters: dict_values (dict) – All simulation inputs
Returns: dict_values – Updated dict_values with pre-processes assets, including economic parameters, busses and auxiliary assets like excess sinks and all assets connected to the energyProviders.
Return type: dict

Notes

Tested with: - test_C0_data_processing.test_process_all_assets_fixcost()

multi_vector_simulator.C0_data_processing.process_maximum_cap_constraint(dict_values, group, asset, subasset=None)¶

Processes the maximumCap constraint depending on its value.

If MaximumCap not in asset dict: MaximumCap is None
If MaximumCap < installedCap: invalid, MaximumCapValueInvalid raised
If MaximumCap == 0: invalid, MaximumCap is None
If group == energyProduction and filename not in asset_dict (dispatchable assets): pass
If group == energyProduction and filename in asset_dict (non-dispatchable assets): MaximumCapNormalized == MaximumCap*peak(timeseries), MaximumAddCapNormalized == MaximumAddCap*peak(timeseries)

Parameters

dict_values (dict) – dictionary of all assets
group (str) – Group that the asset belongs to (str). Used to acces sub-asset data and for error messages.
asset (str) – asset name
subasset (str or None) – subasset name. Default: None.

Notes

Tested with: - test_process_maximum_cap_constraint_maximumCap_undefined() - test_process_maximum_cap_constraint_maximumCap_is_None() - test_process_maximum_cap_constraint_maximumCap_is_int() - test_process_maximum_cap_constraint_maximumCap_is_float() - test_process_maximum_cap_constraint_maximumCap_is_0() - test_process_maximum_cap_constraint_maximumCap_is_int_smaller_than_installed_cap() - test_process_maximum_cap_constraint_group_is_ENERGY_PRODUCTION_fuel_source() - test_process_maximum_cap_constraint_group_is_ENERGY_PRODUCTION_non_dispatchable_asset() - test_process_maximum_cap_constraint_subasset()

Returns

Updates the asset dictionary.
* Unit of MaximumCap is asset unit

multi_vector_simulator.C0_data_processing.process_normalized_installed_cap(dict_values, group, asset, subasset=None)¶

Processes the normalized installed capacity value based on the installed capacity value and the chosen timeseries.

Parameters

dict_values (dict) – dictionary of all assets
group (str) – Group that the asset belongs to (str). Used to acces sub-asset data and for error messages.
asset (str) – asset name
subasset (str or None) – subasset name. Default: None.

Notes

Tested with: - test_process_normalized_installed_cap()

Returns
Return type: Updates the asset dictionary with the normalizedInstalledCap value.

multi_vector_simulator.C0_data_processing.receive_timeseries_from_csv(settings, dict_asset, input_type, is_demand_profile=False)¶

Parameters

settings –
dict_asset –
type –

Returns

multi_vector_simulator.C0_data_processing.replace_nans_in_timeseries_with_0(timeseries, label)¶

Replaces nans in the timeseries (if any) with 0

Parameters

timeseries (pd.Series) – demand or resource timeseries in dict_asset (having nan value(s) if any), also of parameters that are not defined as scalars but as timeseries
label (str) – Contains user-defined information about the timeseries to be printed into the eventual error message

Returns

timeseries – timeseries without NaN values

Return type

pd.Series

Notes

Function tested with - C0.test_replace_nans_in_timeseries_with_0()

multi_vector_simulator.C0_data_processing.treat_multiple_flows(dict_asset, dict_values, parameter)¶: This function consider the case a technical parameter on the json file has a list of values because multiple inputs or outputs busses are considered. :param dict_values: :param dictionary of current values of the asset: :param parameter: :param usually efficiency. Different efficiencies will be given if an asset has multiple inputs or outputs busses: :param : :param so a list must be considered.:

Module C1 - Verification¶

Module C1 is used to validate the input data compiled in A1 or read in B0.

In A1/B0, the input parameters were parsed to str/bool/float/int. This module tests whether the parameters are in correct value ranges: - Display error message when wrong type - Display error message when outside defined range - Display error message when feed-in tariff > electricity price (would cause loop, see #119)

multi_vector_simulator.C1_verification.all_valid_intervals(name, value, title)¶

Checks whether value of name is valid.

Checks include the expected type and the expected range a parameter is supposed to be inside.

Parameters

name –
value –
title –

Returns

multi_vector_simulator.C1_verification.check_efficiency_of_storage_capacity(dict_values)¶

Raises error or logs a warning to help users to spot major change in PR #676.

In #676 the efficiency of storage capacity’ in `storage_*.csv was defined as the storages’ efficiency/ability to hold charge over time. Before it was defined as loss rate. This function raises an error if efficiency of ‘storage capacity’ of one of the storages is 0 and logs a warning if efficiency of ‘storage capacity’ of one of the storages is <0.2.

Parameters: dict_values (dict) – Contains all input data of the simulation.

Notes

Tested with: - test_check_efficiency_of_storage_capacity_is_0 - test_check_efficiency_of_storage_capacity_is_btw_0_and_02 - test_check_efficiency_of_storage_capacity_is_greater_02

Returns

Indirectly, raises error message in case of efficiency of ‘storage capacity’ is 0
and logs warning message in case of efficiency of ‘storage capacity’ is <0.2.

multi_vector_simulator.C1_verification.check_emission_factor_of_providers(dict_values)¶

Logs a logging.warning message in case the grid has a renewable share of 100 % but an emission factor > 0.

This would affect the optimization if a maximum emissions contraint is used. Aditionally, it effects the KPIs connected to emissions.

Parameters

dict_values (dict) – Contains all input data of the simulation.

Returns

Indirectly, logs a logging.warning message in case tthe grid has a renewable share
of 100 % but an emission factor > 0.

Notes

Tested with: - C1.test_check_emission_factor_of_providers_no_warning_RE_share_lower_1() - C1.test_check_emission_factor_of_providers_no_warning_emission_factor_0() - C1.test_check_emission_factor_of_providers_warning()

multi_vector_simulator.C1_verification.check_energy_system_can_fulfill_max_demand(dict_values)¶

Helps to do oemof-solph termination debugging: Logs a logging.warning message if the aggregated installed capacity and maximum capacity (if applicable) of all conversion, generation and storage assets connected to one bus is smaller than the maximum demand. The check is applied to each bus of the energy system. Check passes when the potential peak supply is larger then or equal to the peak demand on the bus, or if the maximum capacity of an asset is set to None when optimizing.

Parameters

dict_values (dict) – Contains all input data of the simulation.

Returns

Indirectly, logs a logging.warning message if the installed and maximum capacities of
conversion/generation/storage assets are less than the maximum demand, for each bus.

Notes

Tested with: - test_check_energy_system_can_fulfill_max_demand_sufficient_capacities() - test_check_energy_system_can_fulfill_max_demand_no_maximum_capacity() - test_check_energy_system_can_fulfill_max_demand_insufficient_capacities() - test_check_energy_system_can_fulfill_max_demand_with_storage() - test_check_energy_system_can_fulfill_max_demand_sufficient_dispatchable_production - test_check_energy_system_can_fulfill_max_demand_insufficient_dispatchable_production - test_check_energy_system_can_fulfill_max_demand_sufficient_non_dispatchable_production - test_check_energy_system_can_fulfill_max_demand_insufficient_non_dispatchable_production - test_check_energy_system_can_fulfill_max_demand_fails_mvs_runthrough

multi_vector_simulator.C1_verification.check_feasibility_of_maximum_emissions_constraint(dict_values)¶

Logs a logging.warning message in case the maximum emissions constraint could lead into an unbound problem.

If the maximum emissions constraint is used it is checked whether there is any production asset with zero emissions that has a capacity to be optimized without maximum capacity constraint. If this is not the case a warning is logged.

Parameters

dict_values (dict) – Contains all input data of the simulation.

Returns

Indirectly, logs a logging.warning message in case the maximum emissions constraint
is used while no production with zero emissions is optimized without maximum capacity.

Notes

Tested with: - C1.test_check_feasibility_of_maximum_emissions_constraint_no_warning_no_constraint() - C1.test_check_feasibility_of_maximum_emissions_constraint_no_warning_although_emission_constraint() - C1.test_check_feasibility_of_maximum_emissions_constraint_maximumcap() - C1.test_check_feasibility_of_maximum_emissions_constraint_optimizeCap_is_False() - C1.test_check_feasibility_of_maximum_emissions_constraint_no_zero_emission_asset()

multi_vector_simulator.C1_verification.check_feedin_tariff_vs_energy_price(dict_values)¶

Raises error if feed-in tariff > energy price of any asset in ‘energyProvider.csv’. This is not allowed, as oemof otherwise is subjected to an unbound and unrealistic problem, eg. one where the owner should consume electricity to feed it directly back into the grid for its revenue.

Parameters

dict_values (dict) – Contains all input data of the simulation.

Returns

Indirectly, raises error message in case of feed-in tariff > energy price of any
asset in ‘energyProvider.csv’.

Notes

Tested with: - C1.test_check_feedin_tariff_vs_energy_price_greater_energy_price() - C1.test_check_feedin_tariff_vs_energy_price_not_greater_energy_price()

multi_vector_simulator.C1_verification.check_feedin_tariff_vs_levelized_cost_of_generation_of_production(dict_values)¶

Raises error if feed-in tariff > levelized costs of generation for energy asset in ENERGY_PRODUCTION with capacity to be optimized and no maximum capacity constraint.

This is not allowed, as oemof otherwise may be subjected to an unbound problem, ie. a business case in which an asset should be installed with infinite capacities to maximize revenue.

In case of a set maximum capacity or no capacity optimization logging messages are logged.

Parameters

dict_values (dict) – Contains all input data of the simulation.

Returns

Raises error message in case of feed-in tariff > levelized costs of generation for energy asset of any
asset in ENERGY_PRODUCTION

Notes

Tested with: - C1.test_check_feedin_tariff_vs_levelized_cost_of_generation_of_production_non_dispatchable_not_greater_costs() - C1.test_check_feedin_tariff_vs_levelized_cost_of_generation_of_production_non_dispatchable_greater_costs() - C1.test_check_feedin_tariff_vs_levelized_cost_of_generation_of_production_dispatchable_higher_dispatch_price() - C1.test_check_feedin_tariff_vs_levelized_cost_of_generation_of_production_dispatchable_lower_dispatch_price() - C1.test_check_feedin_tariff_vs_levelized_cost_of_generation_of_production_non_dispatchable_greater_costs_with_maxcap() - C1.test_check_feedin_tariff_vs_levelized_cost_of_generation_of_production_non_dispatchable_greater_costs_dispatch_mode()

This test does not cover cross-sectoral invalid feedin tariffs. Example: If there is very cheap electricity generation but a high H2 feedin tariff, then it might be a business case to install a large Electrolyzer, and the simulation would fail. In that case one should set bounds to the solution.

multi_vector_simulator.C1_verification.check_for_label_duplicates(dict_values)¶

This function checks if any LABEL provided for the energy system model in dict_values is a duplicate. This is not allowed, as oemof can not build a model with identical labels.

Parameters: dict_values (dict) – All simulation inputs
Returns: pass or error message
Return type: DuplicateLabels

multi_vector_simulator.C1_verification.check_for_sufficient_assets_on_busses(dict_values)¶

Validation check for busses, to make sure a sufficient number of assets is connected.

Each bus has to has to have 3 or more assets connected to it. The reasoning is that each bus needs: - One asset for inflow into the bus - One asset for outflow from the bus - One energy excess asset Note, however, that this test does not check whether the assets actually serve that function, so there might be false negatives: The test can for example pass, if there are two output assets, one excess asset but no input asset, which would represent a non-sensical combination.

On the bus created for the peak demand pricing function (name includes DSO_PEAK_DEMAND_SUFFIX) no excess sinks are added, and therefore the rule does not have to be applied to this bus.

Parameters: dict_values (dict) – All simulation parameters
Returns
Return type: Logging error message if test fails

Notes

This function is tested with: - test_C1_verification.test_check_for_sufficient_assets_on_busses_example_bus_passes() - test_C1_verification.test_check_for_sufficient_assets_on_busses_example_bus_fails() - test_C1_verification.test_check_for_sufficient_assets_on_busses_skipped_for_peak_demand_pricing_bus()

multi_vector_simulator.C1_verification.check_if_energy_vector_is_defined_in_DEFAULT_WEIGHTS_ENERGY_CARRIERS(energy_carrier, asset_group, asset)¶

Raises an error message if an energy vector is unknown.

It then needs to be added to the DEFAULT_WEIGHTS_ENERGY_CARRIERS in constants.py

Parameters

energy_carrier (str) – Name of the energy carrier
asset_group (str) – Name of the asset group
asset (str) – Name of the asset

Returns

Return type

None

Notes

Tested with: - test_check_if_energy_vector_is_defined_in_DEFAULT_WEIGHTS_ENERGY_CARRIERS_pass() - test_check_if_energy_vector_is_defined_in_DEFAULT_WEIGHTS_ENERGY_CARRIERS_fails()

multi_vector_simulator.C1_verification.check_if_energy_vector_of_all_assets_is_valid(dict_values)¶

Validates for all assets, whether ‘energyVector’ is defined within DEFAULT_WEIGHTS_ENERGY_CARRIERS and within the energyBusses.

Parameters: dict_values (dict) – All input data in dict format

Notes

Function tested with - test_add_economic_parameters() - test_check_if_energy_vector_of_all_assets_is_valid_fails - test_check_if_energy_vector_of_all_assets_is_valid_passes

multi_vector_simulator.C1_verification.check_input_values(dict_values)¶

Parameters: dict_values –
Returns

multi_vector_simulator.C1_verification.check_non_dispatchable_source_time_series(dict_values)¶

Raises error if time series of non-dispatchable sources are not between [0, 1].

Parameters

dict_values (dict) – Contains all input data of the simulation.

Returns

Indirectly, raises error message in case of time series of non-dispatchable sources
not between [0, 1].

multi_vector_simulator.C1_verification.check_time_series_values_between_0_and_1(time_series)¶

Checks whether all values of time_series in [0, 1].

Parameters: time_series (pd.Series) – Time series to be checked.
Returns: True if values of time_series within [0, 1], else False.
Return type: bool

multi_vector_simulator.C1_verification.lookup_file(file_path, name)¶

Checks whether file specified in file_path exists.

If it does not exist, a FileNotFoundError is raised.

Parameters

file_path – File name including path of file that is checked.
name – Something referring to which component the file belongs. In get_timeseries_multiple_flows() the label of the asset is used.

Returns

Module C2 - Economic preprocessing¶

Module C2 performs the economic pre-processing of MVS’ input parameters. It includes basic economic formulas.

Functionalities: - Calculate annuity factor - calculate crf depending on year - calculate specific lifetime capex, considering replacement costs and residual value of the asset - calculate annuity from present costs - calculate present costs based on annuity - calculate effective fuel price cost, in case there is a annual fuel price change (this functionality still has to be checked in this module)

multi_vector_simulator.C2_economic_functions.annuity(present_value, crf)¶

Calculates the annuity which is a fixed stream of payments incurred by investments in assets

Parameters

present_value (float) – current equivalent value of a set of future cash flows for an asset
crf (float) – ratio used to calculate the present value of an annuity

Returns

annuity – annuity, i.e. payment made at equal intervals

Return type

float

Notes

Tested with test_annuity()

multi_vector_simulator.C2_economic_functions.annuity_factor(project_life, discount_factor)¶

Calculates the annuity factor, which in turn in used to calculate the present value of annuities (instalments)

Parameters

project_life (int) – time period over which the costs of the system occur
discount_factor (float) – weighted average cost of capital, which is the after-tax average cost of various capital sources

Returns

annuity_factor – financial value “annuity factor”. Dividing a present cost by tha annuity factor returns its annuity, multiplying an annuity with the annuity factor returns its present value

Return type

float

Notes

$annuity factor = \frac{1}{discount factor} - \frac{1}{ discountfactor \cdot (1 + discount factor)^{project life}}$

multi_vector_simulator.C2_economic_functions.capex_from_investment(investment_t0, lifetime, project_life, discount_factor, tax, age_of_asset, asset_label='')¶

Calculates the capital expenditures, also known as CapEx.

CapEx represent the total funds used to acquire or upgrade an asset. The specific capex is calculated by taking into account all future cash flows connected to the investment into one unit of the asset. This includes reinvestments, operation and management costs, dispatch costs as well as a deduction of the residual value at project end. The residual value is calculated with a linear depreciation of the last investment, ie. as a even share of the last investment over the lifetime of the asset. The remaining value of the asset is translated in a present value and then deducted.

Parameters

investment_t0 (float) – first investment at the beginning of the project made at year 0
lifetime (int) – time period over which investments and re-investments can occur. can be equal to, longer or shorter than project_life
project_life (int) – time period over which the costs of the system occur
discount_factor (float) – weighted average cost of capital, which is the after-tax average cost of various capital sources
tax (float) – compulsory financial charge paid to the government
age_of_asset (int) – age since asset installation in year
asset_label (str) – name of the asset

Returns

specific_capex (float) – Specific capital expenditure for an asset over project lifetime
specific_replacement_costs_optimized (float) – Specific replacement costs for the asset capacity to be optimized, needed for E2
specific_replacement_costs_already_installed (float) – replacement costs per unit for the currently already installed assets, needed for E2

Notes

Tested with - test_capex_from_investment_lifetime_equals_project_life() - test_capex_from_investment_lifetime_smaller_than_project_life() - test_capex_from_investment_lifetime_bigger_than_project_life()

multi_vector_simulator.C2_economic_functions.crf(project_life, discount_factor)¶

Calculates the capital recovery ratio used to determine the present value of a series of equal payments (annuity)

Parameters

project_life – time period over which the costs of the system occur
discount_factor – weighted average cost of capital, which is the after-tax average cost of various capital sources

Returns

capital recovery factor, a ratio used to calculate the present value of an annuity

multi_vector_simulator.C2_economic_functions.determine_lifetime_price_dispatch(dict_asset, economic_data)¶

Determines the price of dispatch of an asset LIFETIME_PRICE_DISPATCH and updates the asset info.

It takes into account the asset’s future expenditures due to dispatch. Depending on the price data provided, another function is executed.

Parameters

dict_asset (dict) – Data of an asset
economic_data (dict) – Economic data, including CRF and ANNUITY_FACTOR

Returns

Return type

Updates asset dict

Notes

Tested with - test_determine_lifetime_price_dispatch_as_int() - test_determine_lifetime_price_dispatch_as_float() - test_determine_lifetime_price_dispatch_as_list() - test_determine_lifetime_price_dispatch_as_timeseries ()

multi_vector_simulator.C2_economic_functions.get_lifetime_price_dispatch_list(dispatch_price, economic_data)¶

Determines the lifetime dispatch price in case that the dispatch price is a list.

The dispatch_price can be a list when for example if there are two input flows to a component, eg. water and electricity. There should be a lifetime_price_dispatch for each of them.

$lifetime\_price\_dispatch\_i = DISPATCH\_PRICE\_i \cdot ANNUITY\_FACTOR \forall i$

with $i$ for all list entries

Parameters

dispatch_price (list) – Dispatch prices of the asset as a list
economic_data (dict) – Economic data

Returns

lifetime_price_dispatch – List of floats of lifetime dispatch price that the asset will be updated with

Return type

list

Notes

Tested with - test_determine_lifetime_price_dispatch_as_list() - test_get_lifetime_price_dispatch_list()

multi_vector_simulator.C2_economic_functions.get_lifetime_price_dispatch_one_value(dispatch_price, economic_data)¶

Lifetime dispatch price is a scalar value that is calulated with the annuity

By doing this, the operational expenditures, in the simulation only taken into account for a year, can be compared to the investment costs.

$lifetime_price_dispatch = DISPATCH_PRICE \cdot ANNUITY_FACTOR$

Parameters

dispatch_price (float or int) – dispatch_price of the asset
economic_data (dict) – Economic data

Returns

lifetime_price_dispatch – Float that the asset dict is to be updated with

Return type

float

Notes

Tested with - test_determine_lifetime_price_dispatch_as_int() - test_determine_lifetime_price_dispatch_as_float() - test_get_lifetime_price_dispatch_one_value()

multi_vector_simulator.C2_economic_functions.get_lifetime_price_dispatch_timeseries(dispatch_price, economic_data)¶

Calculates the lifetime price dispatch for a timeseries. The dispatch_price can be a timeseries, eg. in case that there is an hourly pricing. .. math:

lifetime\_price\_dispatch(t) = DISPATCH\_PRICE(t) \cdot ANNUITY\_FACTOR \forall t

Parameters

dispatch_price (pandas.Series) – Dispatch price as a timeseries (eg. electricity prices)
economic_data (dict) – Dict of economic data

Returns

lifetime_price_dispatch – Lifetime dispatch price that the asset will be updated with

Return type

float

Notes

Tested with

test_determine_lifetime_price_dispatch_as_timeseries()
test_get_lifetime_price_dispatch_timeseries()

multi_vector_simulator.C2_economic_functions.get_replacement_costs(age_of_asset, project_lifetime, asset_lifetime, first_time_investment, discount_factor, asset_label='')¶

Calculating the replacement costs of an asset

Parameters

age_of_asset (int) – Age in years of an already installed asset
project_lifetime (int) – Project duration in years
asset_lifetime (int) – Lifetime of an asset in years
first_time_investment (float) – Investment cost of an asset to be installed
discount_factor (float) – Discount factor of a project
asset_label (str) – name of the asset

Returns

Per-unit replacement costs of an asset. If age_asset == 0, they need to be added to the lifetime_specific_costs of the asset.
If age_asset > 0, it will be needed to calculate the future investment costs of a previously installed asset.

multi_vector_simulator.C2_economic_functions.present_value_from_annuity(annuity, annuity_factor)¶

Calculates the present value of future instalments from an annuity

Parameters

annuity (float) – payment made at equal intervals
annuity_factor (float) – financial value

Returns

present_value – present value of future payments from an annuity

Return type

float

multi_vector_simulator.C2_economic_functions.simulation_annuity(annuity, days)¶

Scaling annuity to timeframe Updating all annuities above to annuities “for the timeframe”, so that optimization is based on more adequate costs. Includes project_cost_annuity, distribution_grid_cost_annuity, maingrid_extension_cost_annuity for consistency eventhough these are not used in optimization.

Parameters

annuity (float) – Annuity of an asset
days (int) – Days to be simulated

Returns

Return type

Simulation annuity that considers the lifetime cost for the optimization of one year duration.

Notes

Tested with - test_simulation_annuity_week - test_simulation_annuity_year

Building the energy system model¶

Module D0 - Model building¶

Functional requirements of module D0: - measure time needed to build model - measure time needed to solve model - generate energy system model for oemof - create dictionary of components so that they can be used for constraints and some - raise warning if component not a (in mvs defined) oemof model type - add all energy conversion, energy consumption, energy production, energy storage devices model - plot network graph - at constraints to remote model - store lp file (optional) - start oemof simulation - process results by giving them to the next function - dump oemof results - add simulation parameters to dict values

class multi_vector_simulator.D0_modelling_and_optimization.model_building¶

adding_assets_to_energysystem_model(dict_model, model, **kwargs)¶

Parameters

dict_values (dict) – dict of simulation data
dict_model – Updated list of assets in the oemof energy system model
model (oemof.solph.network.EnergySystem) – Model of oemof energy system

initialize()¶

Initalization of oemof model

Parameters: dict_values (dict) – dictionary of simulation
Returns
Return type: oemof energy model (oemof.solph.network.EnergySystem), dict_model which gathers the assets added to this model later.

plot_networkx_graph(model, save_energy_system_graph=False)¶

Plots a graph of the energy system if that graph is to be displayed or stored.

Parameters

dict_values (dict) – All simulation inputs
model (oemof.solph.network.EnergySystem) – oemof-solph object for energy system model
save_energy_system_graph (bool) – if True, save the graph in the mvs output folder Default: False

Returns

Return type

None

simulating(model, local_energy_system)¶

Initiates the oemof-solph simulation, accesses results and writes main results into dict

If an error is encountered in the oemof solver, mvs should not be allowed to continue, otherwise other errors related to the uncomplete simulation result might occur and it will be more obscure to the endusers what went wrong.

A MVS error is raised if the omoef solver warning states explicitely that “termination condition infeasible”, otherwise the oemof solver warning is re-raised as an error.

Parameters

dict_values (dict) – All simulation inputs
model (object) – oemof-solph object for energy system model
local_energy_system (object) – pyomo object storing all constraints of the energy system model

Returns

Return type

Updated model with results, main results (flows, assets) and meta results (simulation)

store_lp_file(local_energy_system)¶

Stores linear equation system generated with pyomo as an “lp file”.

Parameters

dict_values (dict) – All simulation input data
local_energy_system (object) – pyomo object including all constraints of the energy system

Returns

Return type

Nothing.

multi_vector_simulator.D0_modelling_and_optimization.run_oemof(dict_values, save_energy_system_graph=False)¶

Creates and solves energy system model generated from excel template inputs. Each component is included by calling its constructor function in D1_model_components.

Parameters: values (dict) – Includes all dictionary values describing the whole project, including costs, technical parameters and components. In C0_data_processing, each component was attributed with a certain in/output bus.
Returns
Return type: saves and returns oemof simulation results

class multi_vector_simulator.D0_modelling_and_optimization.timer¶

initalize()¶: Starts a timer

stop(start)¶

Ends timer and adds duration of simulation to dict_values :param dict_values: Dict of simulation including SIMULATION_RESULTS key :type dict_values: dict :param start: start time of timer :type start: timestamp

Returns
Return type: Simulation time in dict_values

Module D1 - Oemof components¶

Module D1 includes all functions that are required to build an oemof model with adaptable components.

add transformer objects (fix, to be optimized)
add source objects (fix, to be optimized, dispatchable, non-dispatchable)
add sink objects (fix, to be optimized, dispatchable, non-dispatchable)
add storage objects (fix, to be optimized)
add multiple input/output busses if required for each of the assets
add oemof component parameters as scalar or time series values

multi_vector_simulator.D1_model_components.bus(model, name, **kwargs)¶

Adds bus name to model and to ‘busses’ in kwargs.

Notes

Tested with: - test_bus_add_to_empty_dict() - test_bus_add_to_not_empty_dict()

multi_vector_simulator.D1_model_components.check_optimize_cap(model, dict_asset, func_constant, func_optimize, **kwargs)¶

Defines a component specified in dict_asset with fixed capacity or capacity to be optimized.

Parameters

model (oemof.solph.network.EnergySystem object) – See the oemof documentation for more information.
dict_asset (dict) – Contains information about the asset like (not exhaustive): efficiency, installed capacity (‘installedCap’), information on the busses the asset is connected to (f.e. ‘inflow_direction’, ‘outflow_direction’).
func_constant (func) – Function to be applied if optimization not intended.
func_optimize (func) – Function to be applied if optimization not intended.
are busses and a dictionary belonging to the respective oemof (Required) –
of the asset. (type) –
busses (dict, optional) –
sinks (dict, optional) –
sources (dict, optional) –
transformers (dict, optional) –
storages (dict, optional) –

Returns

Indirectly updated model and dict of asset in kwargs with the component object.
TODOS
^^^^^
Might be possible to drop non invest optimization in favour of invest optimization if max_capactiy
attributes ie. are set to 0 for fix (but less beautiful, and in case of generator even blocks nonconvex opt.).

Notes

Tested with: - test_check_optimize_cap_raise_error()

multi_vector_simulator.D1_model_components.sink(model, dict_asset, **kwargs)¶

Defines a sink component specified in dict_asset.

Depending on the ‘value’ of ‘optimizeCap’ in dict_asset the sink is defined with a fixed capacity or a capacity to be optimized. If a time series is provided for the sink (key ‘timeseries’ in dict_asset) it is defined as a non dispatchable sink, otherwise as dispatchable sink. The sink has multiple or a single input bus depending on the type of the key ‘inflow_direction’ in dict_asset.

Parameters

model (oemof.solph.network.EnergySystem object) – See the oemof documentation for more information.
dict_asset (dict) – Contains information about the storage like (not exhaustive): efficiency, installed capacity (‘installedCap’), information on the busses the sink is connected to (‘inflow_direction’),
busses (dict) –
sinks (dict) –
sources (dict, optional) –
transformers (dict, optional) –
storages (dict, optional) –

Notes

The following functions are used for defining the sink: * sink_non_dispatchable() * sink_dispatchable()

Tested with: - test_sink_non_dispatchable_single_input_bus() - test_sink_non_dispatchable_multiple_input_busses() - test_sink_dispatchable_single_input_bus() - test_sink_dispatchable_multiple_input_busses()

multi_vector_simulator.D1_model_components.sink_dispatchable_optimize(model, dict_asset, **kwargs)¶

Define a dispatchable sink.

The dispatchable sink is capacity-optimized, without any costs connected to the capacity of the asset. Applications of this asset type are: Feed-in sink, excess sink.

See sink() for more information, including parameters.

Notes

Tested with: - test_sink_dispatchable_single_input_bus() - test_sink_dispatchable_multiple_input_busses()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the sink object.

multi_vector_simulator.D1_model_components.sink_non_dispatchable(model, dict_asset, **kwargs)¶

Defines a non dispatchable sink.

See sink() for more information, including parameters.

Notes

Tested with: - test_sink_non_dispatchable_single_input_bus() - test_sink_non_dispatchable_multiple_input_busses()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the sink object.

multi_vector_simulator.D1_model_components.source(model, dict_asset, **kwargs)¶

Defines a source component specified in dict_asset.

Depending on the ‘value’ of ‘optimizeCap’ in dict_asset the source is defined with a fixed capacity or a capacity to be optimized. If a time series is provided for the source (key ‘timeseries’ in dict_asset) it is defined as a non dispatchable source, otherwise as dispatchable source. The source has multiple or a single output bus depending on the type of the key ‘inflow_direction’ in dict_asset.

Parameters

model (oemof.solph.network.EnergySystem object) – See the oemof documentation for more information.
dict_asset (dict) – Contains information about the storage like (not exhaustive): efficiency, installed capacity (‘installedCap’), information on the busses the sink is connected to (‘inflow_direction’),
busses (dict) –
sinks (dict) –
sources (dict, optional) –
transformers (dict, optional) –
storages (dict, optional) –
TODOS –
^^^^^ –
We should actually not allow multiple output busses (*) –
- because a pv would then (probably) –
in twice as much as solar_gen_specific for example (feed) –
issue #121 (see) –

Notes

The following functions are used for defining the source: * source_dispatchable_fix() * source_dispatchable_optimize() * source_non_dispatchable_fix() * source_non_dispatchable_optimize()

Tested with: - test_source_non_dispatchable_optimize() - test_source_non_dispatchable_fix() - test_source_dispatchable_optimize_normalized_timeseries() - test_source_dispatchable_optimize_timeseries_not_normalized_timeseries() - test_source_dispatchable_fix_normalized_timeseries() - test_source_dispatchable_fix_timeseries_not_normalized_timeseries()

multi_vector_simulator.D1_model_components.source_dispatchable_fix(model, dict_asset, **kwargs)¶

Defines a dispatchable source with a fixed capacity.

See source() for more information, including parameters.

Notes

Tested with: - test_source_dispatchable_fix_normalized_timeseries() - test_source_dispatchable_fix_timeseries_not_normalized_timeseries()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the source object.

multi_vector_simulator.D1_model_components.source_dispatchable_optimize(model, dict_asset, **kwargs)¶

Defines a dispatchable source with a fixed capacity.

See source() for more information, including parameters.

Notes

Tested with: - test_source_dispatchable_optimize_normalized_timeseries() - test_source_dispatchable_optimize_timeseries_not_normalized_timeseries()

Returns

Indirectly updated model and dict of asset in kwargs with the source object.

multi_vector_simulator.D1_model_components.source_non_dispatchable_fix(model, dict_asset, **kwargs)¶

Defines a non dispatchable source with a fixed capacity.

See source() for more information, including parameters.

Notes

Tested with: - test_source_non_dispatchable_fix()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the source object.

multi_vector_simulator.D1_model_components.source_non_dispatchable_optimize(model, dict_asset, **kwargs)¶

Defines a non dispatchable source with a capacity to be optimized.

See source() for more information, including parameters.

Notes

Tested with: - test_source_non_dispatchable_optimize()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the source object.

multi_vector_simulator.D1_model_components.storage(model, dict_asset, **kwargs)¶

Defines a storage component specified in dict_asset.

Depending on the ‘value’ of ‘optimizeCap’ in dict_asset the storage is defined with a fixed capacity or a capacity to be optimized.

Parameters

model (oemof.solph.network.EnergySystem object) – See the oemof documentation for more information.
dict_asset (dict) – Contains information about the storage like (not exhaustive): efficiency, installed capacity (‘installedCap’), information on the busses the storage is connected to (‘inflow_direction’, ‘outflow_direction’),
busses (dict) –
sinks (dict, optional) –
sources (dict, optional) –
transformers (dict, optional) –
storages (dict) –

Notes

The following functions are used for defining the storage: * storage_fix() * storage_optimize()

Tested with: - test_storage_optimize() - test_storage_fix()

multi_vector_simulator.D1_model_components.storage_fix(model, dict_asset, **kwargs)¶

Defines a storage with a fixed capacity.

See storage() for more information, including parameters.

Notes

Tested with: - test_storage_fix()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the storage object.

multi_vector_simulator.D1_model_components.storage_optimize(model, dict_asset, **kwargs)¶

Defines a storage with a capacity to be optimized.

See storage() for more information, including parameters.

Notes

Tested with: - test_storage_optimize() - test_storage_optimize_investment_minimum_0_float() - test_storage_optimize_investment_minimum_0_time_series() - test_storage_optimize_investment_minimum_1_rel_float() - test_storage_optimize_investment_minimum_1_abs_float() - test_storage_optimize_investment_minimum_1_rel_times_series() - test_storage_optimize_investment_minimum_1_abs_times_series()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the storage object.

multi_vector_simulator.D1_model_components.transformer(model, dict_asset, **kwargs)¶

Defines a transformer component specified in dict_asset.

Depending on the ‘value’ of ‘optimizeCap’ in dict_asset the transformer is defined with a fixed capacity or a capacity to be optimized. The transformer has multiple or single input or output busses depending on the types of keys ‘inflow_direction’ and ‘outflow_direction’ in dict_asset.

Parameters

model (oemof.solph.network.EnergySystem object) – See the oemof documentation for more information.
dict_asset (dict) – Contains information about the transformer like (not exhaustive): efficiency, installed capacity (‘installedCap’), information on the busses the transformer is connected to (‘inflow_direction’, ‘outflow_direction’).
busses (dict) –
sinks (dict, optional) –
sources (dict, optional) –
transformers (dict) –
storages (dict, optional) –

Notes

The transformer has either multiple input or multiple output busses.

The following functions are used for defining the transformer: * transformer_constant_efficiency_fix() * transformer_constant_efficiency_optimize()

Tested with: - test_transformer_optimize_cap_single_busses() - test_transformer_optimize_cap_multiple_input_busses() - test_transformer_optimize_cap_multiple_output_busses() - test_transformer_fix_cap_single_busses() - test_transformer_fix_cap_multiple_input_busses() - test_transformer_fix_cap_multiple_output_busses()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with transformer object.

multi_vector_simulator.D1_model_components.transformer_constant_efficiency_fix(model, dict_asset, **kwargs)¶

Defines a transformer with constant efficiency and fixed capacity.

See transformer() for more information, including parameters.

Notes

Tested with: - test_transformer_fix_cap_single_busses() - test_transformer_fix_cap_multiple_input_busses() - test_transformer_fix_cap_multiple_output_busses()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the transformer object.

multi_vector_simulator.D1_model_components.transformer_constant_efficiency_optimize(model, dict_asset, **kwargs)¶

Defines a transformer with constant efficiency and a capacity to be optimized.

See transformer() for more information, including parameters.

Notes

Tested with: - test_transformer_optimize_cap_single_busses() - test_transformer_optimize_cap_multiple_input_busses() - test_transformer_optimize_cap_multiple_output_busses()

Returns
Return type: Indirectly updated model and dict of asset in kwargs with the transformer object.

Module D2 - Model constraints¶

This module gathers all constraints that can be added to the MVS optimisation. we will probably require another input CSV file or further parameters in simulation_settings.

Future constraints are discussed in issue #133 (https://github.com/rl-institut/multi-vector-simulator/issues/133)

constraints should be tested in-code (examples) and by comparing the lp file generated.

multi_vector_simulator.D2_model_constraints.add_constraints(local_energy_system, dict_values, dict_model)¶

Adds all constraints activated in constraints.csv to the energy system model.

Possible constraints: - Minimal renewable factor constraint :param local_energy_system: Energy system model generated from oemof-solph for the energy system scenario, including all energy system assets. :type local_energy_system: :oemof-solph: <oemof.solph.model> :param dict_values: All simulation parameters :type dict_values: dict :param dict_model: Dictionary including the oemof-solph component assets, which need to be connected with constraints :type dict_model: dict of :oemof-solph: <oemof.solph.assets>

Returns

local_energy_system – Updated object local_energy_system with the additional constraints and bounds.

Return type

oemof-solph: <oemof.solph.model>

Notes

The constraints can be validated by evaluating the LP file. Additionally, there are validation tests in E4_verification_of_constraints.

Tested with: - D2.test_add_constraints_maximum_emissions() - D2.test_add_constraints_maximum_emissions_None() - D2.test_add_constraints_minimal_renewable_share() - D2.test_add_constraints_minimal_renewable_share_is_0() - D2.test_add_constraints_net_zero_energy_requirement_is_true() - D2.test_add_constraints_net_zero_energy_requirement_is_false()

multi_vector_simulator.D2_model_constraints.constraint_maximum_emissions(model, dict_values, dict_model=None)¶

Resulting in an energy system adhering to a maximum amount of emissions.

Parameters

model – Model to which constraint is added.
dict_values (dict) – All simulation parameters
dict_model (None) – To match other constraint function’s format

Notes

Tested with: - D2.test_constraint_maximum_emissions()

multi_vector_simulator.D2_model_constraints.constraint_minimal_degree_of_autonomy(model, dict_values, dict_model)¶

Resulting in an energy system adhering to a minimal degree of autonomy.

Please be aware that the minimal degree of autonomy is not applied to each sector individually, but to the overall energy system (via energy carrier weighting).

Parameters

model – Model to which constraint is added.
dict_values (dict) – All simulation parameters
dict_model (dict of :oemof-solph: <oemof.solph.assets>) – Dictionary including the oemof-solph component assets, which need to be connected with constraints

Notes

The renewable factor of the whole energy system has to adhere for following constraint:

$minimal degree of autonomy \cdot (\sum local demand \cdot weighting factor) <= \sum local demand \cdot weighting factor - \sum consumtion from energy providers \cdot weighting factor$

Tested with: - Test_Constraints.test_benchmark_minimal_degree_of_autonomy()

multi_vector_simulator.D2_model_constraints.constraint_minimal_renewable_share(model, dict_values, dict_model)¶

Resulting in an energy system adhering to a minimal renewable factor.

Please be aware that the renewable factor that has to adhere to the minimal renewable factor is not the one of one specific sector, but of the overall energy system. This means that eg. 1 kg H2 is produced renewably, it goes into account with a heavier weighting factor then one renewably produced electricity unit.

Parameters

model – Model to which constraint is added.
dict_values (dict) – All simulation parameters
dict_model (dict of :oemof-solph: <oemof.solph.assets>) – Dictionary including the oemof-solph component assets, which need to be connected with constraints

Notes

The renewable factor of the whole energy system has to adhere for following constraint:

$minimal renewable factor <= \frac{\sum renewable generation \cdot weighting factor}{\sum renewable generation \cdot weighting factor + \sum non-renewable generation \cdot weighting factor}$

Tested with: - Test_Constraints.test_benchmark_minimal_renewable_share_constraint()

multi_vector_simulator.D2_model_constraints.constraint_net_zero_energy(model, dict_values, dict_model)¶

Resulting in an energy system that is a net zero energy (NZE) or plus energy system.

Please be aware that the NZE constraint is not applied to each sector individually, but to the overall energy system (via energy carrier weighting).

Parameters

model – Model to which constraint is added.
dict_values (dict) – All simulation parameters
dict_model (dict of :oemof-solph: <oemof.solph.assets>) – Dictionary including the oemof-solph component assets, which need to be connected with constraints

Notes

The constraint reads as follows:

$\sum_{i} {E_{feedin, DSO} (i) \cdot w_i - E_{consumption, DSO} (i) \cdot w_i} >= 0$

Tested with: - Test_Constraints.test_net_zero_energy_constraint()

multi_vector_simulator.D2_model_constraints.prepare_constraint_minimal_renewable_share(dict_values, dict_model)¶

Prepare creating the minimal renewable factor constraint by processing dict_values

Parameters

dict_values (dict) – All simulation parameters
dict_model (dict of :oemof-solph: <oemof.solph.assets>) – Dictionary including the oemof-solph component assets, which need to be connected with constraints

Returns

renewable_assets (dict) – Dictionary of all assets with renewable generation in the energy system. Defined by: oemof_solph_object_asset, weighting_factor_energy_carrier, renewable_share_asset_flow, oemof_solph_object_bus
non_renewable_assets (dict) – Dictionary of all assets with renewable generation in the energy system. Defined by: oemof_solph_object_asset, weighting_factor_energy_carrier, renewable_share_asset_flow, oemof_solph_object_bus

multi_vector_simulator.D2_model_constraints.prepare_demand_assets(dict_values, dict_model)¶

Perpare demand assets by processing dict_values

Used for the following constraints: - minimal degree of autonomy

Parameters

dict_values (dict) – All simulation parameters
dict_model (dict of :oemof-solph: <oemof.solph.assets>) – Dictionary including the oemof-solph component assets, which need to be connected with constraints

Notes

Tested with: - test_prepare_demand_assets()

Returns: demands – Dictionary of all assets with all demands in the energy system. Defined by: oemof_solph_object_asset, weighting_factor_energy_carrier, oemof_solph_object_bus
Return type: dict

multi_vector_simulator.D2_model_constraints.prepare_energy_provider_consumption_sources(dict_values, dict_model)¶

Prepare energy provider consumption sources by processing dict_values.

Used for the following constraints: - minimal degree of autonomy - net zero energy (NZE)

Parameters

dict_values (dict) – All simulation parameters
dict_model (dict of :oemof-solph: <oemof.solph.assets>) – Dictionary including the oemof-solph component assets, which need to be connected with constraints

Notes

Tested with: - test_prepare_energy_provider_consumption_sources()

Returns: energy_provider_consumption_sources – Dictionary of all assets that are sources for the energy consumption from energy providers in the energy system. Defined by: oemof_solph_object_asset, weighting_factor_energy_carrier, oemof_solph_object_bus
Return type: dict

multi_vector_simulator.D2_model_constraints.prepare_energy_provider_feedin_sinks(dict_values, dict_model)¶

Prepare energy provider feedin sinks by processing dict_values.

Used for the following constraints: - net zero energy (NZE)

Parameters

dict_values (dict) – All simulation parameters
dict_model (dict of :oemof-solph: <oemof.solph.assets>) – Dictionary including the oemof-solph component assets, which need to be connected with constraints

Notes

Tested with:

test_prepare_energy_provider_feedin_sinks()

Returns: energy_provider_feedin_sinks – Dictionary of all assets that are sinks for the energy feed-in to energy providers in the energy system. Defined by: oemof_solph_object_asset, weighting_factor_energy_carrier, oemof_solph_object_bus
Return type: dict

Post-processing and evaluation¶

Module E0 - evaluation¶

Module E0 evaluates the oemof results and calculates the KPI - define dictionary entry for kpi matrix - define dictionary entry for cost matrix - store all results to matrix

multi_vector_simulator.E0_evaluation.evaluate_dict(dict_values, results_main, results_meta)¶

Processes all simulation outputs by evaluating oemof results, asset capacities and dispatch as well as all KPIs.

Parameters

dict_values (dict) – simulation parameters
results_main (DataFrame) – oemof simulation results as output by processing.results()
results_meta (DataFrame) – oemof simulation meta information as output by processing.meta_results()

Notes

Tested with: - test_E0.evaluation.test_evaluate_dict_append_new_fields() - test_E0.evaluation.test_evaluate_dict_important_fields_in_output_dict() - test_E0.evaluation.test_evaluate_dict_fields_values_in_output_dict_are_dataframes()

multi_vector_simulator.E0_evaluation.initalize_kpi(dict_values)¶

Adds basic structure of KPI to dict_values to gather them later on.

Parameters: dict_values (dict) – All simulation data, but without any results
Returns
Return type: Updated dict_values with KPI structure, made up from KPI_COST_MATRIX, KPI_SCALAR_MATRIX and KPI_SCALARS_DICT.

multi_vector_simulator.E0_evaluation.process_fixcost(dict_values)¶

Adds fix costs of the project to the economic evaluation of the energy system.

Parameters: dict_values (dict) – All simulation data with inputs and results of the assets
Returns
Return type: Updated dict_values with costs attributed in dict values also appended to the dict_values[KPI] (scalar results)

Notes

Function is tested with: - test_E0_evaluation.test_process_fixcost()

multi_vector_simulator.E0_evaluation.store_result_matrix(dict_kpi, dict_asset, fix_cost=False)¶

Storing results to vector and then result matrix for saving it in csv. Defined value types: Str, bool, None, dict (with key “VALUE”), else (int, float)

Parameters

dict_kpi (dict) – dictionary with the two kpi groups (costs and scalars), which are pd.DF
dict_asset (dict) – all information known for a specific asset
fix_cost (Boolean) – If fix_cost is True, then no new row is added to KPI_SCALAR_MATRIX, as there are no KPI to update. Costs in KPI_COST_MATRIX however are added.

Returns

Return type

Updated dict_kpi DF, with new row of kpis of the specific asset.

Module E1 process results¶

Module E1 processes the oemof results. - receive time series per bus for all assets - write time series to dictionary - get optimal capacity of optimized assets - add the evaluation of time series

multi_vector_simulator.E1_process_results.add_info_flows(evaluated_period, dict_asset, flow, type=None)¶

Adds flow and total flow amongst other information to dict_asset.

Parameters

evaluated_period (int) – The number of days simulated with the energy system model.
dict_asset (dict) – Contains information about the asset flow belongs to.
flow (pd.Series) – Time series of the flow.
type (str, default: None) – type of the flow, only exception is “STORAGE_CAPACITY”.

Returns

Indirectly updates dict_asset with the flow, the total flow, the annual
total flow, the maximum of the flow (‘peak_flow’) and the average value of
the flow (‘average_flow’). As Storage capacity is not a flow, an aggregation of the timeseries does not make sense
and the parameters TOTAL_FLOW, ANNUAL_TOTAL_FLOW, PEAK_FLOW, AVERAGE_FLOW are added set to None.

Notes

Tested with: - E1.test_add_info_flows_365_days() - E1.test_add_info_flows_1_day() - E1.test_add_info_flows_storage_capacity()

multi_vector_simulator.E1_process_results.convert_components_to_dataframe(dict_values)¶

Dataframe used for the component table of the report

Parameters: dict_values (dict) – output values of MVS
Returns
Return type: pandas.DataFrame

Notes

Tested with:

test_E1_process_results.test_convert_components_to_dataframe()

multi_vector_simulator.E1_process_results.convert_cost_matrix_to_dataframe(dict_values)¶

Dataframe used for the cost matrix table of the report

Parameters: dict_values (dict) – output values of MVS
Returns
Return type: pandas.DataFrame

multi_vector_simulator.E1_process_results.convert_costs_to_dataframe(dict_values)¶

Dataframe used for the costs piecharts of the report

Parameters: dict_values (dict) – output values of MVS
Returns
Return type: pandas.DataFrame

multi_vector_simulator.E1_process_results.convert_demand_to_dataframe(dict_values, sector_demands=None)¶

Dataframe used for the demands table of the report

Parameters

dict_values (dict) – output values of MVS
sector_demands (str) – Name of the sector of the energy system whose demands must be returned as a df by this function Default: None

Returns

Return type

pandas.DataFrame

multi_vector_simulator.E1_process_results.convert_kpi_sector_to_dataframe(dict_values)¶

Processes the sector KPIs so that they can be included in the report

Parameters: dict_values (dict) – output values of MVS
Returns: kpi_sectors_dataframe – Dataframe to be displayed as a table in the report
Return type: pandas.DataFrame

Notes

Currently, as the KPI_UNCOUPLED_DICT does not hold any units, the table printed in the report is unit-les.

multi_vector_simulator.E1_process_results.convert_scalar_matrix_to_dataframe(dict_values)¶

Dataframe used for the scalar matrix table of the report

Parameters: dict_values (dict) – output values of MVS
Returns
Return type: pandas.DataFrame

multi_vector_simulator.E1_process_results.convert_scalars_to_dataframe(dict_values)¶

Processes the scalar system-wide KPI so that they can be included in the report

Parameters: dict_values (dict) – output values of MVS
Returns: kpi_scalars_dataframe – Dataframe to be displayed as a table in the report
Return type: pandas.DataFrame

Notes

Currently, as the KPI_SCALARS_DICT does not hold any units, the table printed in the report is unit-les.

multi_vector_simulator.E1_process_results.cut_below_micro(value, label)¶

Function trims results of oemof optimization to positive values and rounds to 0, if within a certain precision threshold (of -10^-6)

Oemof termination is dependent on the simulation settings of oemof solph. Thus, it can terminate the optimization if the results are with certain bounds, which can sometimes lead to negative decision variables (capacities, flows). Negative values do not make sense in this context. If the values are between -10^-6 and 0, we assume that they can be rounded to 0, as they result from the precision settings of the solver. In that case the value is overwritten for the futher post-processing. This should also avoid SOC timeseries with doubtful values outside of [0,1]. If any value is a higher negative value then the threshold, its value is not changed but a warning raised. Similarily, if a positive devision variable is detected that has a value lower then the theshold, it is assumed that this only happends because of the solver settings, and the values below the theshold are rounded to 0.

Parameters

value (float or pd.Series) – Decision variable determined by oemof
label (str) – String to be mentioned in the debug messages

Returns

value – Decision variable with rounded values in case that slight negative values or positive values were observed.

Return type

float of pd.Series

Notes

Tested with: - E1.test_cut_below_micro_scalar_value_below_0_larger_threshold - E1.test_cut_below_micro_scalar_value_below_0_smaller_threshold - E1.test_cut_below_micro_scalar_value_0 - E1.test_cut_below_micro_scalar_value_larger_0 - E1.test_cut_below_micro_scalar_value_larger_0_smaller_threshold - E1.test_cut_below_micro_pd_Series_below_0_larger_threshold - E1.test_cut_below_micro_pd_Series_below_0_smaller_threshold - E1.test_cut_below_micro_pd_Series_0 - E1.test_cut_below_micro_pd_Series_larger_0 - E1.test_cut_below_micro_pd_Series_larger_0_smaller_threshold

multi_vector_simulator.E1_process_results.get_flow(settings, bus, dict_asset, flow_tuple)¶

Adds flow of bus and total flow amongst other information to dict_asset.

Depending on direction the input or the output flow is used.

Parameters

settings (dict) – Contains simulation settings from simulation_settings.csv with additional information like the amount of time steps simulated in the optimization (‘periods’).
bus (dict) –

Contains information about a specific bus. Information about the scalars, if they exist,
like investment or initial capacity in key ‘scalars’ (pd.Series) and the flows between the component and the bus(ses) in key ‘sequences’ (pd.DataFrame).
dict_asset (dict) – Contains information about the asset.
flow_tuple (tuple) – Entry of the oemof-solph outputs to be evaluated

Returns

Indirectly updates dict_asset with the flow of bus, the total flow, the annual
total flow, the maximum of the flow (‘peak_flow’) and the average value of
the flow (‘average_flow’).

multi_vector_simulator.E1_process_results.get_optimal_cap(bus, dict_asset, flow_tuple)¶

Retrieves optimized capacity of asset specified in dict_asset.

Parameters

bus (dict) – Contains information about the busses linked to the asset specified in dict_asset. Information about the scalars like investment or initial capacity in key ‘scalars’ (pd.Series) and the flows between the component and the busses in key ‘sequences’ (pd.DataFrame).
dict_asset (dict) – Contains information about the asset.
flow_tuple (tuple) – Key of the oemof-solph outputs dict mapping the value to be evaluated

Returns

Indirectly updated dict_asset with optimal capacity to be added
(‘optimizedAddCap’).
TODOS
^^^^^
* direction as optimal parameter or with default value None (direction is – not needed if ‘optimizeCap’ is not in dict_asset or if it’s value is False

multi_vector_simulator.E1_process_results.get_parameter_to_be_evaluated_from_oemof_results(asset_group, asset_label)¶

Determine the parameter that needs to be evaluated to determine an asset`s optimized flow and capacity.

Parameters

asset_group (str) – Asset group to which the evaluated asset belongs
asset_label (str) – Label of the asset, needed for log message

Returns

parameter_to_be_evaluated – Parameter that will be processed to get the dispatch and capacity of an asset

Return type

str

Notes

Tested by: - test_get_parameter_to_be_evaluated_from_oemof_results()

multi_vector_simulator.E1_process_results.get_results(settings, bus_data, dict_asset, asset_group)¶

Reads results of the asset defined in dict_asset and stores them in dict_asset.

Parameters

settings (dict) – Contains simulation settings from simulation_settings.csv with additional information like the amount of time steps simulated in the optimization (‘periods’).
bus_data (dict) –
Contains information about all busses in a nested dict. 1st level keys: bus names; 2nd level keys:

’scalars’: (pd.Series) (does not exist in all dicts) ‘sequences’: (pd.DataFrame) - contains flows between components and busses
dict_asset (dict) – Contains information about the asset.
asset_group (str) – Asset group to which the evaluated asset belongs

Returns

Return type

Indirectly updates dict_asset with results.

multi_vector_simulator.E1_process_results.get_state_of_charge_info(dict_asset)¶

Adds state of charge timeseries and average value of the timeseries to the storage dict.

Parameters: dict_asset (dict) – Dict of the asset, specifically including the STORAGE_CAPACITY
Returns
Return type: Updated dict_asset

Notes

Tested with: - E1.test_get_state_of_charge_info()

multi_vector_simulator.E1_process_results.get_storage_results(settings, storage_bus, dict_asset)¶

Reads storage results of simulation and stores them in dict_asset.

Parameters

settings (dict) – Contains simulation settings from simulation_settings.csv with additional information like the amount of time steps simulated in the optimization (‘periods’).
storage_bus (dict) – Contains information about the storage bus. Information about the scalars like investment or initial capacity in key ‘scalars’ (pd.Series) and the flows between the component and the busses in key ‘sequences’ (pd.DataFrame).
dict_asset (dict) – Contains information about the storage like capacity, charging power, etc.

Returns

Indirectly updates dict_asset with simulation results concerning the
storage.

multi_vector_simulator.E1_process_results.get_timeseries_per_bus(dict_values, bus_data)¶

Reads simulation results of all busses and stores time series.

Parameters

dict_values (dict) – Contains all input data of the simulation.
bus_data (dict Contains information about all busses in a nested dict.) –
1st level keys: bus names; 2nd level keys:

’scalars’: (pd.Series) (does not exist in all dicts) ‘sequences’: (pd.DataFrame) - contains flows between components and busses

Notes

Tested with: - test_get_timeseries_per_bus_two_timeseries_for_directly_connected_storage()

#Todo: This is a duplicate of the E1.get_flow() assertions, and thus E1.cut_below_micro is applied twice for each flow. This should rather be merged into the other functions.

Returns
Return type: Indirectly updated dict_values with ‘optimizedFlows’ - one data frame for each bus.

multi_vector_simulator.E1_process_results.get_tuple_for_oemof_results(asset_label, asset_group, bus)¶

Determines the tuple with which to access the oemof-solph results

The order of the parameters in the tuple depends on the direction of the flow. If the asset is defined… a) …by its influx from a bus, the bus has to be named first in the touple b) …by its outflux into a bus, the asset has to be named first in the touple

Parameters

asset_label (str) – Name of the asset
asset_group (str) – Asset group the asset belongs to
bus (str) – Bus that is to be accessed for the asset´s information

Returns

flow_tuple – Keys to be accessed in the oemof-solph results

Return type

tuple of str

Notes

Tested with - test_get_tuple_for_oemof_results()

multi_vector_simulator.E1_process_results.get_units_of_cost_matrix_entries(dict_economic, kpi_list)¶

Determines the units of the costs KPI to be stored to :class: DataFrame.

Parameters

dict_economic – Economic project data
kpi_list – List of cost matrix entries

Returns

unit_list – List of units for the :class: DataFrame to be created

Return type

list

multi_vector_simulator.E1_process_results.translate_optimizeCap_from_boolean_to_yes_no(optimize_cap)¶

Translates the boolean OPTIMIZE_CAP to a yes-no value for readability of auto report

Parameters: optimize_cap (bool) – Setting whether asset is optimized or not
Returns: optimize – If OPTIMIZE_CAP==True: “Yes”, else “No”.
Return type: str

Notes

Tested with: - test_E1_process_results.test_translate_optimizeCap_from_boolean_to_yes_no()

Module E2 - Economic processing¶

The module processes the simulation results regarding economic parameters: - calculate lifetime expenditures based on variable energy flows - calculate lifetime investment costs - calculate present value of an asset - calculate revenue - calculate yearly cash flows of whole project for project lifetime (cash flow projection) - calculate fuel price expenditures calculate upfront investment costs - calculate operation management costs (FOM) - calculate upfront investment costs (UIC) - calculate annuity per asset - calculate annuity for the whole project - calculate net present value - calculate levelised cost of energy - calculate levelised cost of energy carriers (electricity, H2, heat)

exception multi_vector_simulator.E2_economics.MissingParametersForEconomicEvaluation¶: Warning if one or more parameters are missing for economic post-processing of an asset

multi_vector_simulator.E2_economics.all_list_in_dict(dict_asset, list)¶

Checks if all items of a list are withing the keys of a dictionary

Parameters

dict_asset (dict) – Dict with the keys to be evaluated
list (list) – List of keys (parameter in strings) that should be in dict

Returns

boolean – True: All items in keys of the dict False: At least one item is not in keys of the dict

Return type

bool

multi_vector_simulator.E2_economics.calculate_costs_replacement(specific_replacement_of_initial_capacity, specific_replacement_of_optimized_capacity, initial_capacity, optimized_capacity)¶

Calculate (the present value of) the replacement costs over the project lifetime

Parameters

specific_replacement_of_initial_capacity (float) – Per-unit replacement costs of an asset that was pre-existing at the location
specific_replacement_of_optimized_capacity (float) – Per-unit replacement costs of an asset that is to be installed
initial_capacity (float) – Initial capacity installed
optimized_capacity (float) – Additional capacity to be installed, as optimized

Returns

costs_replacements – Aggregated replacement costs over the project lifetime

Return type

float

multi_vector_simulator.E2_economics.calculate_costs_upfront_investment(specific_cost, capacity, development_costs)¶

Calculate investment costs of an asset Depending on the specific_cost provided, either the total asset’s lifetime investment costs or the upfront investment costs are calculated,

Parameters

specific_cost (float) –
1. Specific per-unit investment costs of an asset over its lifetime, including all replacement costs
2. Specific per-unit investment costs of an asset in year 0
capacity (float) – Capacity to be installed
development_costs (float) – Fix development costs, ie. an expense not related to the capacity that is installed. Could be planning costs of the asset.

Returns

costs_investment – a) Total investment costs of an asset over its lifetime, including all replacement costs b) Upfront investment costs in year 0

Return type

float

multi_vector_simulator.E2_economics.calculate_dispatch_expenditures(dispatch_price, flow, asset)¶

Calculate the expenditures connected to an asset due to its dispatch

Parameters

dispatch_price (float, int or pd.Series) – Dispatch price of an asset (variable costs), ie. how much has to be paid for each unit of dispatch Raises error if type does not match a) lifetime_price_dispatch (taking into account all years of operation) b) price_dispatch (taking into account one year of operation)
flow (pd.Series) – Dispatch of the asset
asset (str) – Label of the asset

Returns

a) Total dispatch expenditures of an asset
b) Annual dispatch expenditures of an asset

multi_vector_simulator.E2_economics.calculate_operation_and_management_expenditures(specific_om_cost, installed_capacity, optimized_add_capacity)¶

Calculate operation and management expenditures

Parameters

specific_om_cost (float) –
1. specific operation and management costs per unit in year 0
2. specific operation and management costs per unit for the whole project lifetime
installed_capacity (float) – Capacity installed initially
optimized_add_capacity (float) – Capacity installed within the optimization scenario

Returns

costs_operation_and_management – a) Operation and management expenditures in year 0 b) Total operation and management expenditures over the project lifetime

Return type

float

multi_vector_simulator.E2_economics.calculate_total_asset_costs_over_lifetime(costs_investment, cost_operational_expenditures)¶

Calculate costs of an asset over whole lifetime

Parameters

costs_investment (float) – Investment costs over whole lifetime
cost_operational_expenditures (float) – Operation and management as well as dispatch expenditures over whole lifetime

Returns

total_asset_costs_over_lifetime – costs of an asset over whole lifetime, including upfront investment costs, development costs, replacement costs, operation and management expenditures, dispatch expenditures

Return type

float

multi_vector_simulator.E2_economics.calculate_total_capital_costs(upfront, replacement)¶

Calculate total capital expenditures

Parameters

upfront (float) – Upfront investments at t=0, including development costs
replacement (float) – Replacement costs of pre-installed and new assets

Returns

cost_total_investment – Total capital costs

Return type

float

multi_vector_simulator.E2_economics.calculate_total_operational_expenditures(operation_and_management_expenditures, dispatch_expenditures)¶

Calculate total expenditures of an asset (operational costs)

Parameters

operation_and_management_expenditures (float) –
1. operation and management expenditures per annum for the installed capacity
2. operation and management expenditures for whole project lifetime for the installed capacity
dispatch_expenditures (float) –
1. dispatch expenditures per annum for the installed capacity
2. dispatch expenditures for whole project lifetime for the installed capacity

Returns

total_operational_expenditures – a) total operational expenditures per annum for installed capacity b) total operational expenditures for whole project lifetime for installed capacity

Return type

float

multi_vector_simulator.E2_economics.get_costs(dict_asset, economic_data)¶

Calculates economic KPI of the asset handed to the function

Parameters

dict_asset (dict) – Asset to be evaluated. Warning messages in place in case that the asset should not be evaluated.
economic_data (dict) – Economic data of the project

Returns

Updated dict_asset with following KPI
- COST_INVESTMENT
- COST_UPFRONT
- COST_REPLACEMENT
- COST_TOTAL
- COST_OM
- COST_DISPATCH
- COST_OPERATIONAL_TOTAL
- ANNUITY_TOTAL
- ANNUITY_OM
Tested with
- test_all_cost_info_parameters_added_to_dict_asset()
- Test_Economic_KPI.test_benchmark_Economic_KPI_C2_E2()

multi_vector_simulator.E2_economics.lcoe_assets(dict_asset, asset_group)¶

Calculates the levelized cost of electricity (lcoe) of each asset. [Follow this link for information](docs/MVS_Outputs.rst)

Parameters

dict_asset (dict) – Dictionary defining an asset
asset_group (str) – Defining to which asset group the asset belongs

Returns

Updates the asset dictionary with the calculated LCOE_ASSET.
Storages have four values LCOE_ASSET (One for the overall storage including all costs, and one each for the components.)

Notes

$LCOE\_ASSET = \frac{A}{ E_{throughput} } \\ \textrm{If } E_{throughput} = 0, LCOE\_ASSET = 0$

Module E3 - Indicator calculation¶

In module E3 the technical KPI are evaluated: - calculate renewable share - calculate degree of autonomy (DA) - calculate degree of net zero energy (NZE) - calculate total generation of each asset and total_internal_generation - calculate total feedin electricity equivalent - calculate energy flows between sectors - calculate degree of sector coupling - calculate onsite energy fraction (OEF) - calculate onsite energy matching (OEM)

multi_vector_simulator.E3_indicator_calculation.add_degree_of_autonomy(dict_values)¶

Determines degree of autonomy and adds KPI to dict_values

Parameters

dict_values (dict) – dict with all project information and results, after applying total_renewable_and_non_renewable_energy_origin and total_demand_and_excess_each_sector

Returns

None – updated dict_values with the degree of autonomy
Tested with
- test_add_degree_of_autonomy()

multi_vector_simulator.E3_indicator_calculation.add_degree_of_net_zero_energy(dict_values)¶

Determines degree of net zero energy (NZE) and adds KPI to dict_values.

Parameters: dict_values (dict) – dict with all project information and results, after applying total_renewable_and_non_renewable_energy_origin and total_demand_and_excess_each_sector
Returns: updated dict_values with the degree of net zero energy
Return type: None

Notes

As for other KPI, we apply a weighting based on Electricity Equivalent.

Tested with - test_add_degree_of_net_zero_energy()

multi_vector_simulator.E3_indicator_calculation.add_degree_of_sector_coupling(dict_values)¶

Determines the aggregated flows in between the sectors and the Degree of Sector Coupling.

Takes into account the value of different energy carriers.

Parameters

dict_values (dict) – dictionary with all project inputs and results, specifically the energyConversion assets and the outputs.

Returns

Energy equivalent of total conversion flows
.. math:: – E_{conversion,eq} = sum_{i}{E_{conversion} (i) cdot w_i} with i are conversion assets

multi_vector_simulator.E3_indicator_calculation.add_levelized_cost_of_energy_carriers(dict_values)¶

Adds levelized costs of all energy carriers and overall system to the scalar KPI.

Parameters: dict_values (dict) – All simulation inputs and results
Returns: Updated KPI_SCALAR_DICT
Return type: Add ATTRIBUTED_COSTS and LCOeleq for each energy carrier as well as LCOeleq for overall energy system

Notes

Tested with:

test_E3_indicator_calculation.test_add_levelized_cost_of_energy_carriers_one_sector()
test_E3_indicator_calculation.test_add_levelized_cost_of_energy_carriers_two_sectors()

multi_vector_simulator.E3_indicator_calculation.add_onsite_energy_fraction(dict_values)¶

Determines onsite energy fraction (OEF), i.e. self-consumption, and adds KPI to dict_values

Parameters

dict_values (dict) – dict with all project information and results after applying total_renewable_and_non_renewable_energy_origin

Returns

None – updated dict_values with onsite energy fraction KPI
Tested with
- test_add_onsite_energy_fraction()

multi_vector_simulator.E3_indicator_calculation.add_onsite_energy_matching(dict_values)¶

Determines onsite energy matching (OEM), i.e. self-sufficiency, and adds KPI to dict_values

Parameters

dict_values (dict) – dict with all project information and results after applying total_renewable_and_non_renewable_energy_origin and total_demand_and_excess_each_sector and add_onsite_energy_fraction

Returns

None – updated dict_values with onsite energy matching KPI
Tested with
- test_add_onsite_energy_matching()

multi_vector_simulator.E3_indicator_calculation.add_renewable_factor(dict_values)¶

Determination of renewable share of one sector

Parameters: dict_values – dict with all project information and results, after applying add_total_renewable_and_non_renewable_energy_origin
Returns: updated dict_values with renewable factor of each sector as well as system-wide indicator
Return type: type

Notes

Updates the KPI with RENEWABLE_FACTOR for each sector as well as system-wide KPI.

Tested with - test_renewable_factor_one_sector - test_renewable_factor_two_sectors - TestTechnicalKPI.renewable_factor_and_renewable_share_of_local_generation()

multi_vector_simulator.E3_indicator_calculation.add_renewable_share_of_local_generation(dict_values)¶

Determination of renewable share of local energy production

Parameters

dict_values :: dict with all project information and results, after applying add_total_renewable_and_non_renewable_energy_origin
sector :: Sector for which renewable share is being calculated
:returns: updated dict_values with renewable share of each sector as well as the system-wide KPI
:rtype: type
.. rubric:: Notes
Updates the KPI with RENEWABLE_SHARE_OF_LOCAL_GENERATION for each sector as well as system-wide KPI.
Tested with
* test_renewable_share_of_local_generation_one_sector()
* test_renewable_share_of_local_generation_two_sectors()
* TestTechnicalKPI.renewable_factor_and_renewable_share_of_local_generation()

multi_vector_simulator.E3_indicator_calculation.add_specific_emissions_per_electricity_equivalent(dict_values)¶

Calculates the specific emissions of the energy system per kWheleq and adds KPI to dict_values.

Parameters: dict_values (dict) – All simulation inputs and results including TOTAL_EMISSIONS calculated in E3.calculate_emissions_from_flow.

Notes

This funtion is run after E3.calculate_emissions_from_flow.

Tested with: - E3.test_add_specific_emissions_per_electricity_equivalent()

Returns: Updated dict_values with SPECIFIC_EMISSIONS_ELEQ in kgCO2eq/kWheleq (UNIT_SPECIFIC_EMISSIONS).
Return type: None

multi_vector_simulator.E3_indicator_calculation.add_total_consumption_from_provider_electricity_equivalent(dict_values)¶

Determines the total consumption from energy providers with weighting of electricity equivalent.

Parameters: dict_values (dict) – dict with all project information and results
Returns: updated dict_values with KPI : - TOTAL_CONSUMPTION_FROM_PROVIDERS + electricity, - TOTAL_CONSUMPTION_FROM_PROVIDERS + electricity + SUFFIX_ELECTRICITY_EQUIVALENT - TOTAL_CONSUMPTION_FROM_PROVIDERS + SUFFIX_ELECTRICITY_EQUIVALENT
Return type: None

Notes

Tested with: - E3.test_add_total_consumption_from_provider_electricity_equivalent()

multi_vector_simulator.E3_indicator_calculation.add_total_emissions(dict_values)¶

Calculates the total emission of the energy system in kgCO2eq/a and adds KPI to dict_values.

Parameters: dict_values (dict) – All simulation inputs and results
Returns: Updated dict_values with TOTAL_EMISSIONS of the energy system in kgCO2eq/a (UNIT_EMISSIONS).
Return type: None

Notes

Tested with: - E3.test_add_total_emissions()

multi_vector_simulator.E3_indicator_calculation.add_total_feedin_electricity_equivalent(dict_values)¶

Determines the total grid feed-in with weighting of electricity equivalent.

Parameters

dict_values (dict) – dict with all project information and results

Returns

None – updated dict_values with KPI : total feedin
Tested with
- test_add_total_feedin_electricity_equivalent()

multi_vector_simulator.E3_indicator_calculation.add_total_renewable_and_non_renewable_energy_origin(dict_values)¶

Identifies all renewable generation assets and summs up their total generation to total renewable generation

Parameters: dict_values – dict with all project input data and results up to E0
Returns: Updated dict_values with total internal/overall renewable and non-renewable energy origin
Return type: type

Notes

Tested with - test_total_renewable_and_non_renewable_origin_of_each_sector()

multi_vector_simulator.E3_indicator_calculation.all_totals(dict_values)¶

Calculate sum of all cost parameters

Parameters: dict_values – dict all input parameters and results up to E0
Returns: List of all total cost parameters for the project
Return type: type

Notes

The totals are calculated for following parameters: - costs_total - costs_om_total - costs_investment_over_lifetime - costs_upfront_in_year_zero - costs_dispatch - costs_cost_om - annuity_total - annuity_om

The levelized_cost_of_energy_of_asset are dropped from the list, as they do not hold any actual meaning for the whole energy system. The LCOE of the energy system is calculated seperately.

multi_vector_simulator.E3_indicator_calculation.calculate_electricity_equivalent_for_a_set_of_aggregated_values(dict_values, dict_of_aggregated_flows, kpi_name)¶

Calculates the electricity equivalent for a dict of aggregated flows and writes it to the KPI

Parameters

dict_values (dict) – All simulation parameters
dict_of_aggregated_flows (dict) – Dict of aggragated flows, with keys of energy carriers.
kpi_name (str) – Name of the KPI to write to the results

Returns

Return type

Updated dict_values.

multi_vector_simulator.E3_indicator_calculation.calculate_emissions_from_flow(dict_asset)¶

Calculates the total emissions of the asset in ‘dict_asset’ in kg per year.

Parameters: dict_asset (dict) – Contains information about the asset.

Notes

Tested with: - E3.test_calculate_emissions_from_flow() - E3.test_calculate_emissions_from_flow_zero_emissions

Returns: Updated dict_asset with TOTAL_EMISSIONS of the asset in kgCO2eq/a (UNIT_EMISSIONS).
Return type: None

multi_vector_simulator.E3_indicator_calculation.equation_degree_of_autonomy(total_consumption_from_energy_provider, total_demand)¶

Calculates the degree of autonomy (DA).

The degree of autonomy describes the relation of how much demand is supplied by local generation (as opposed to grid conumption) compared to the total demand of the system.

Parameters

total_consumption_from_energy_provider (float) – total energy consumption from providers
total_demand (float) – total demand

Returns

float – degree of autonomy
.. math:: – DA &=frac{sum_i {E_{demand} (i) cdot w_i} - sum_{i} {E_{consumption,provider,j} (j) cdot w_j}}{sum_i {E_{demand} (i) cdot w_i}}
A DA = 0 (Demand is fully supplied by DSO consumption)
DA = 1 (System is autonomous, ie. no DSO consumption is necessary)
Notice (As above, we apply a weighting based on Electricity Equivalent.)
Tested with
- test_equation_degree_of_autonomy()

multi_vector_simulator.E3_indicator_calculation.equation_degree_of_net_zero_energy(total_feedin, total_grid_consumption, total_demand)¶

Calculates the degree of net zero energy (NZE).

In NZE systems import and export of energy is allowed while the balance over one year should be zero, thus the degree of net zero energy would be 1. The Degree of net zero energy indicates how close the system gets to the NZE ideal. If more energy is exported than imported it is plus-energy system (degree of NZE > 1).

Parameters

total_feedin (float) – total grid feed-in in electricity equivalents
total_grid_consumption (float) – total consumption from energy provider in electricity equivalents
total_demand (float) – total demand in electricity equivalents

Returns

degree of net zero energy

Return type

float

Notes

$Degree of NZE &= 1 + \frac{(\sum_{i} {E_{grid feedin}(i)} \cdot w_i - E_{grid consumption} (i) \cdot w_i)}{\sum_i {E_{demand, i} \cdot w_i}}$

Degree of NZE = 1 : System is a net zero energy system, as E_feedin = E_grid_consumption Degree of NZE > 1 : system is a plus-energy system, as E_feedin > E_grid_consumption Degree of NZE < 1 : system does not reach net zero balance. The degree indicates by how much it fails to do so. Degree of NZE = 0 : system has no internal production, as E_dem = E_grid_consumption.

Tested with - test_equation_degree_of_net_zero_energy() - test_equation_degree_of_net_zero_energy_is_zero() - test_equation_degree_of_net_zero_energy_is_one() - test_equation_degree_of_net_zero_energy_greater_one()

multi_vector_simulator.E3_indicator_calculation.equation_degree_of_sector_coupling(total_flow_of_energy_conversion_equivalent, total_demand_equivalent)¶

Calculates degree of sector coupling.

Parameters

total_flow_of_energy_conversion_equivalent (float) – Energy equivalent of total conversion flows
total_demand_equivalent (float) – Energy equivalent of total energy demand

Returns

float – Degree of sector coupling based on conversion flows and energy demands in electricity equivalent.
.. math:: –

DSC=frac{sum_{i,j}{E_{conversion} (i,j) cdot w_i}}{sum_i {E_{demand} (i) cdot w_i}}

with i,j epsilon [Electricity,H2…]

multi_vector_simulator.E3_indicator_calculation.equation_levelized_cost_of_energy_carrier(cost_total, crf, total_flow_energy_carrier_eleq, total_demand_electricity_equivalent, total_flow_energy_carrier)¶

Calculates LCOE of each energy carrier of the system.

Based on distributing the NPC of the energy system over the total weighted energy demand of the local energy system. This avoids that a conversion asset has to be defined as being used for a specific sector only, or that an energy production asset (eg. electricity) which is mainly used for powering energy conversion assets for another energy carrier (eg. H2) are increasing the costs of the first energy carrier (electricity), eventhough the costs should be attributed to the costs of the end-use of generation.

Parameters

cost_total (float) –
crf (float) –
total_flow_energy_carrier_eleq (float) –
total_demand_electricity_equivalent (float) –
total_flow_energy_carrier (float) –

Returns

lcoe_energy_carrier (float) – Levelized costs of an energy carrier in a sector coupled system
attributed_costs (float) – Costs attributed to a specific energy carrier

Notes

Please refer to the conference paper presented at the CIRED Workshop Berlin (see readthedocs) for more detail.

The costs attributed to an energy carrier are calculated from the ratio of electricity equivalent of the energy carrier demand in focus to the electricity equivalent of the total demand:

$attributed costs = NPC \cdot \frac{Total electricity equivalent of energy carrier demand}{Total electricity equivalent of demand}$

The LCOE sets these attributed costs in relation to the energy carrier demand (in its original unit):

$LCOE energy carrier = \frac{attributed costs \cdot CRF}{total energy carrier demand}$

Tested with: - test_equation_levelized_cost_of_energy_carrier_total_demand_electricity_equivalent_larger_0_total_flow_energy_carrier_larger_0() - test_equation_levelized_cost_of_energy_carrier_total_demand_electricity_equivalent_larger_0_total_flow_energy_carrier_is_0() - test_equation_levelized_cost_of_energy_carrier_total_demand_electricity_equivalent_is_0_total_flow_energy_carrier_is_0()

multi_vector_simulator.E3_indicator_calculation.equation_onsite_energy_fraction(total_generation, total_feedin)¶

Calculates onsite energy fraction (OEF), i.e. self-consumption.

OEF describes the fraction of all locally generated energy that is consumed by the system itself.

Parameters

total_generation (float) – Energy equivalent of total generation flows
total_feedin (float) – Total feed into the grid

Returns

float – Onsite energy fraction.
.. math:: – OEF &=frac{sum_{i} {E_{generation} (i) cdot w_i} - E_{gridfeedin}(i) cdot w_i}{sum_{i} {E_{generation} (i) cdot w_i}} &OEF epsilon text{[0,1]}
Tested with
- test_equation_onsite_energy_fraction()

multi_vector_simulator.E3_indicator_calculation.equation_onsite_energy_matching(total_generation, total_feedin, total_excess, total_demand)¶

Calculates onsite energy matching (OEM), i.e. self-sufficiency.

OEM describes the fraction of the total demand that can be covered by the locally generated energy.

Parameters

total_generation (float) – Energy equivalent of total conversion flows
total_feedin (float) – Total feed into the grid
total_excess (float) – Total Excess energy
total_demand (float) – Total demand

Returns

Onsite energy matching.
.. math:: – OEM &=frac{sum_{i} {E_{generation} (i) cdot w_i} - E_{gridfeedin}(i) cdot w_i - E_{excess}(i) cdot w_i}{sum_i {E_{demand} (i) cdot w_i}}

&OEM epsilon text{[0,1]}
Tested with
- test_equation_onsite_energy_matching()

multi_vector_simulator.E3_indicator_calculation.equation_renewable_share(total_res, total_non_res)¶

Calculates the renewable share

Parameters

total_res – Renewable generation of a system
total_non_res – Non-renewable generation of a system

Returns

Renewable share

Return type

type

Notes

Used both to calculate RENEWABLE_FACTOR and RENEWABLE_SHARE_OF_LOCAL_GENERATION.

Equation:

$RES = \frac{total_res}{total_non_res + total_res}$

The renewable share is relative to generation, but not consumption of energy, the renewable share can not be larger 1. If there is no generation or consumption from a DSO within an energyVector and supply is solely reached by energy conversion from another vector, the renewable share is defined to be zero.

renewable share = 1 - all energy in the energy system is of renewable origin
renewable share < 1 - part of the energy in the system is of renewable origin
renewable share = 0 - no energy is of renewable origin

Tested with:

test_renewable_share_equation_no_generation()
test_renewable_share_equation_below_1()
test_renewable_share_equation_is_0()
test_renewable_share_equation_is_1()

multi_vector_simulator.E3_indicator_calculation.total_demand_and_excess_each_sector(dict_values)¶

Calculation of the total demand and total excess of each sector

Both in original energy carrier unit and electricity equivalent

Parameters

dict_values – dict with all project input data and results up to E0

Returns

Updated KPI_SCALARS_DICT with
- total demand of each energy carrier (original unit)
- total demand of each energy carrier (electricity equivalent)
- total demand in electricity equivalent
- total excess of each energy carrier (original unit)
- total excess of each energy carrier (electricity equivalent)
- total excess in electricity equivalent

Notes

Tested with - test_add_levelized_cost_of_energy_carriers_one_sector() - test_add_levelized_cost_of_energy_carriers_two_sectors() - TestTechnicalKPI.renewable_factor_and_renewable_share_of_local_generation()

multi_vector_simulator.E3_indicator_calculation.weighting_for_sector_coupled_kpi(dict_values, kpi_name)¶

Calculates the weighted kpi for a specific kpi_name both for a single sector and system-wide

Parameters

dict_values – dict with all project information and results, including KPI_UNCOUPLED_DICT with the specifc kpi_name in question
kpi_name – str with the kpi which should be weighted

Returns

Append specific KPI that describes sector-coupled system to dict_values[KPI][KPI_SCALARS_DICT] Appends specific KPI in energy equivalent to each sector to dict_values[KPI][KPI_UNCOUPLED_DICT]

Return type

type

Module E4 - Verification of results¶

Detect excessive excess generation
Verify that minimal renewable share constraint is adhered to
Verfiy that maximum emission constraint is adhered to
Verfiy that net zero energy (NZE) constraint is adhered to

multi_vector_simulator.E4_verification.detect_excessive_excess_generation_in_bus(dict_values)¶

Warning for any bus with excessive excess generation is given.

A logging.warning message is printed when the ratio between total outflows and total inflows of a bus is < 0.9.

Parameters

dict_values –

Returns

- Nothing if the there is no excessive excess generation
- Prints logging.warning message for every bus with excessive excess generation.

multi_vector_simulator.E4_verification.maximum_emissions_test(dict_values)¶

Tests if maximum emissions constraint was correctly applied.

Parameters

dict_values (dict) – all input parameters and results up to E0

Returns

Nothing
- Nothing if the constraint is confirmed
- Prints logging.warning message if the difference from the constraint is < 10^-6.
- Prints a logging.error message if the difference from the constraint is >= 10^-6.

Notes

Tested with: - E4.test_maximum_emissions_test_passes() - E4.test_maximum_emissions_test_fails()

multi_vector_simulator.E4_verification.minimal_constraint_test(dict_values, minimal_constraint, bounded_result)¶

Test if minimal constraint was correctly applied

Parameters

dict_values (dict) – Dict of all simulation information
minimal_constraint (str) – Key to access the value of the minimal bound of parameter subjected to constraint to be tested
bounded_result (str) – Key to access the value of the resulting parameter to be compared to minimal_bound

Returns

Nothing
- Nothing if the constraint is confirmed
- Prints logging.warning message if the deviation from the constraint is < 10^-6.
- Prints a logging.error message if the deviation from the constraint is >= 10^-6.

Notes

Executed to test - MINIMAL_DEGREE_OF_AUTONOMY vs. RENEWABLE_FACTOR - MINIMAL_RENEWABLE_FACTOR vs. DEGREE_OF_AUTONOMY

Tested with: - E4.test_minimal_constraint_test_passes() - E4.test_minimal_constraint_test_fails()

multi_vector_simulator.E4_verification.net_zero_energy_constraint_test(dict_values)¶

Tests if net zero energy constraint was correctly applied.

Parameters

dict_values (dict) – all input parameters and results up to E0

Returns

Nothing
- Nothing if the constraint is confirmed
- Prints logging.warning message if the difference from the constraint is < 10^-6.
- Prints a logging.error message if the difference from the constraint is >= 10^-6.

Notes

Tested with: - E4.test_net_zero_energy_constraint_test_fails() - E4.test_net_zero_energy_constraint_test_passes()

multi_vector_simulator.E4_verification.verify_state_of_charge(dict_values)¶

This function checks the state of charge of each storage component It raises warning log messages if the SoC has a physically infeasible value

Parameters

dict_values (dict) – Dictionary with all information regarding the simulation, specifically including the energyStorage assets

Returns

- Nothing if there are no physically infeasible SoC values for the storage components
- Prints log messages to console and log file if there are physically impossible SoC values

Notes

Tested with: - test_E4_verification.test_verify_state_of_charge_feasible() - test_E4_verification.test_verify_state_of_charge_soc_below_zero() - test_E4_verification.test_verify_state_of_charge_soc_above_zero()

Output¶

Module F0 - Output¶

The model F0 output defines all functions that store evaluation results to file. - Aggregate demand profiles to a total demand profile - Plot all energy flows for both 14 and 365 days for each energy bus - Store timeseries of all energy flows to excel (one sheet = one energy bus) - Execute function: plot optimised capacities as a barchart (F1) - Execute function: plot all annuities as a barchart (F1) - Store scalars/KPI to excel - Process dictionary so that it can be stored to Json - Store dictionary to Json

multi_vector_simulator.F0_output.evaluate_dict(dict_values, path_pdf_report=None, path_png_figs=None)¶

This is the main function of F0. It calls all functions that prepare the simulation output, ie. Storing all simulation output into excellent files, bar charts, and graphs.

Parameters

dict_values – dict Of all input and output parameters up to F0
path_pdf_report ((str)) – if provided, generate a pdf report of the simulation to the given path
path_png_figs ((str)) – if provided, generate png figures of the simulation’s results to the given path

Returns

NA

Return type

type

multi_vector_simulator.F0_output.parse_simulation_log(path_log_file, dict_values)¶

Gather a log file with several log messages, this function gathers them all and inputs them into the dict with all input and output parameters up to F0

Parameters

path_log_file (str/None) – path to the mvs log file Default: None
dict_values – dict Of all input and output parameters up to F0

Returns

Return type

Updates the results dictionary with the log messages of the simulation

multi_vector_simulator.F0_output.store_as_json(dict_values, output_folder=None, file_name=None)¶

Converts dict_values to JSON format and saves dict_values as a JSON file or return json

Parameters

dict_values ((dict)) – dict to be stored as json
output_folder ((path)) – Folder into which json should be stored Default None
file_name ((str)) – Name of the file the json should be stored as Default None

Returns

If file_name is provided, the json variable converted from the dict_values is saved under
this file_name, otherwise the json variable is returned

multi_vector_simulator.F0_output.store_scalars_to_excel(dict_values)¶

All output data that is a scalar is storage to an excellent file tab. This could for example be economical data or technical data.

Parameters: dict_values – dict Of all input and output parameters up to F0
Returns: Excel file with scalar data
Return type: type

multi_vector_simulator.F0_output.store_timeseries_all_busses_to_excel(dict_values)¶

This function plots the energy flows of each single bus and the energy system and saves it as PNG and additionally as a tab and an Excel sheet.

Parameters: dict_values – dict Of all input and output parameters up to F0
Returns: Plots and excel with all timeseries of each bus
Return type: type

Module F1 - Plotting¶

Module F1 describes all the functions that create plots.

creating graphs for energy flows
creating bar chart for capacity
creating pie chart for cost data
creating network graph for the model brackets only working on Ubuntu

class multi_vector_simulator.F1_plotting.ESGraphRenderer(energy_system=None, filepath='network', img_format=None, legend=True, txt_width=10, txt_fontsize=10, **kwargs)¶

add_bus(label='Bus', subgraph=None)¶

add_component(label='component', subgraph=None)¶

add_sink(label='Sink', subgraph=None)¶

add_source(label='Source', subgraph=None)¶

add_storage(label='Storage', subgraph=None)¶

add_transformer(label='Transformer', subgraph=None)¶

connect(a, b)¶

Draw an arrow from node a to node b

Parameters

a (oemof.solph.network.Node) – An oemof node (usually a Bus or a Component)
b (oemof.solph.network.Node) – An oemof node (usually a Bus or a Component)

render(**kwargs)¶: Call the render method of the DiGraph instance

view(**kwargs)¶: Call the view method of the DiGraph instance

multi_vector_simulator.F1_plotting.convert_plot_data_to_dataframe(plot_data_dict, data_type)¶

Parameters

plot_data_dict (dict) – timeseries for either demand or supply
data_type (str) – one of DEMANDS or RESOURCES

Returns

df – timeseries for plotting

Return type

pandas:pandas.DataFrame<frame>,

multi_vector_simulator.F1_plotting.create_plotly_barplot_fig(x_data, y_data, plot_title=None, trace_name='', legends=None, x_axis_name=None, y_axis_name=None, file_name='barplot.png', file_path=None)¶

Create figure for specific capacities barplot

Parameters

x_data (list, or pandas series) – The list of abscissas of the data required for plotting.
y_data (list, or pandas series, or list of lists) – The list of ordinates of the data required for plotting.
plot_title (str) – The title of the plot generated. Default: None
trace_name (str) – Sets the trace name. The trace name appear as the legend item and on hover. Default: “”
legends (list, or pandas series) – The list of the text written within the bars and on hover below the trace_name Default: None
x_axis_name (str) – Default: None
y_axis_name (str) – Default: None
file_name (str) – Name of the image file. Default: “barplot.png”
file_path (str) – Path where the image shall be saved if not None

Returns

fig – figure object

Return type

plotly.graph_objs.Figure

multi_vector_simulator.F1_plotting.create_plotly_flow_fig(df_plots_data, x_legend=None, y_legend=None, plot_title=None, color_list=None, file_name='flows.png', file_path=None)¶

Generate figure of an asset’s flow.

Parameters

df_plots_data (pandas.DataFrame) – dataFrame with timeseries of the asset’s energy flow
x_legend (str) – Default: None
y_legend (str) – Default: None
plot_title (str) – Default: None
color_list (list of str or list to tuple (hexadecimal or rbg code)) – list of colors Default: None
file_name (str) – Name of the image file. Default: “flows.png”
file_path (str) – Path where the image shall be saved if not None Default: None

Returns

fig – figure object

Return type

plotly.graph_objs.Figure

multi_vector_simulator.F1_plotting.create_plotly_line_fig(x_data, y_data, plot_title=None, x_axis_name=None, y_axis_name=None, color_for_plot='#0A2342', file_path=None)¶

Create figure for generic timeseries lineplots

Parameters

x_data (list, or pandas series) – The list of abscissas of the data required for plotting.
y_data (list, or pandas series, or list of lists) – The list of ordinates of the data required for plotting.
plot_title (str) – The title of the plot generated. Default: None
x_axis_name (str) – Default: None
y_axis_name (str) – Default: None
file_path (str) – Path where the image shall be saved if not None

Returns

figure object

Return type

fig plotly.graph_objs.Figure

multi_vector_simulator.F1_plotting.create_plotly_piechart_fig(title_of_plot, names, values, color_scheme=None, file_name='costs.png', file_path=None)¶

Generate figure with piechart plot.

Parameters

title_of_plot (str) – title of the figure
names (list) – List containing the labels of the slices in the pie plot.
values (list) – List containing the values of the labels to be plotted in the pie plot.
color_scheme (instance of the px.colors class of the Plotly express library) – This parameter holds the color scheme which is palette of colors (list of hex values) to be applied to the pie plot to be created. Default: None
file_name (str) – Name of the image file. Default: “costs.png”
file_path (str) – Path where the image shall be saved if not None Default: None

Returns

fig – figure object

Return type

plotly.graph_objs.Figure

multi_vector_simulator.F1_plotting.extract_plot_data_and_title(dict_values, df_dem=None)¶

Dataframe used for the plots of demands and resources timeseries in the report

Parameters

dict_values (dict) – output values of MVS
df_dem (pandas.DataFrame) – summarized demand information for each demand

Returns

Return type

pandas.DataFrame

multi_vector_simulator.F1_plotting.fixed_width_text(text, char_num=10)¶

Add linebreaks every char_num characters in a given text.

Parameters

text (obj:'str') – text to apply the linebreaks
char_num (obj:'int') – max number of characters in a line before a line break Default: 10

Returns

obj – the text with line breaks after every char_num characters

Return type

‘str’

multi_vector_simulator.F1_plotting.get_color(idx_line, color_list=None)¶

Pick a color within a color list with periodic boundary conditions

Parameters

idx_line (int) – index of the line in a plot for which a color is required
colors (list of str or list to tuple (hexadecimal or rbg code)) – list of colors Default: None

Returns

Return type

The color in the color list corresponding to the index modulo the color list length

multi_vector_simulator.F1_plotting.get_fig_style_dict()¶

multi_vector_simulator.F1_plotting.plot_instant_power(dict_values, file_path=None)¶

Plotting timeseries of instantaneous power for each assets within the energy system

Parameters

dict_values (dict) – all simulation input and output data up to this point
file_path (str) – Path where the image shall be saved if not None Default: None

Returns

multi_plots – Dict with html DOM id for the figure as keys and plotly.graph_objs.Figure as values

Return type

dict

multi_vector_simulator.F1_plotting.plot_optimized_capacities(dict_values, file_path=None)¶

Plot capacities as a bar chart.

Parameters

dict_values – dict Of all input and output parameters up to F0
file_path (str) – Path where the image shall be saved if not None Default: None

Returns

Return type

Dict with html DOM id for the figure as key and plotly.graph_objs.Figure as value

multi_vector_simulator.F1_plotting.plot_piecharts_of_costs(dict_values, file_path=None)¶

Plotting piecharts of different cost parameters (ie. annuity, total cost, etc…)

Parameters

dict_values (dict) – all simulation input and output data up to this point
file_path (str) – Path where the image shall be saved if not None Default: None

Returns

pie_plots – Dict with html DOM id for the figure as keys and plotly.graph_objs.Figure as values

Return type

dict

multi_vector_simulator.F1_plotting.plot_timeseries(dict_values, data_type='demands', sector_demands=None, max_days=None, color_list=None, file_path=None)¶

Plot timeseries as line chart.

Parameters

dict_values – dict Of all input and output parameters up to F0
data_type (str) – one of DEMANDS or RESOURCES Default: DEMANDS
sector_demands (str) – Name of the sector of the energy system Default: None
max_days (int) – maximal number of days the timeseries should be displayed for
color_list (list of str or list to tuple (hexadecimal or rbg code)) – list of colors Default: None
file_path (str) – Path where the image shall be saved if not None Default: None

Returns

Return type

Dict with html DOM id for the figure as key and plotly.graph_objs.Figure as value

multi_vector_simulator.F1_plotting.save_plots_to_disk(fig_obj, file_name, file_path='', width=None, height=None, scale=None)¶

This function saves the plots generated using the Plotly library in this module to the outputs folder.

Parameters

fig_obj (instance of the classes of the Plotly go library used to generate the plots in this auto-report) – Figure object of the plotly plots
file_name (str) – The name of the PNG image of the plot to be saved in the output folder.
file_path (str) – Path where the image shall be saved
width (int or float) – The width of the picture to be saved in pixels. Default: None
height (int or float) – The height of the picture to be saved in pixels. Default: None
scale (int or float) – The scale by which the plotly image ought to be multiplied. Default: None

Returns

Return type

Nothing is returned. This function call results in the plots being saved as .png images to the disk.

Module F2 - Autoreport¶

This script generates a report of the simulation automatically, with all the important data.

multi_vector_simulator.F2_autoreport.create_app(results_json, path_sim_output=None)¶

Initializes the app and calls all the other functions, resulting in the web app as well as pdf.

This function specifies the layout of the web app, loads the external styling sheets, prepares the necessary data from the json results file, calls all the helper functions on the data, resulting in the auto-report.

Parameters

results_json (json results file) – This file is the result of the simulation and contains all the data necessary to generate the auto-report.
path_sim_output (str) – Path to the mvs simulation’s output files’ folder Default: output path saved in the result_json

Returns

app – This app holds together all the html elements wrapped in Python, necessary for the rendering of the auto-report.

Return type

instance of the Dash class within the dash library

multi_vector_simulator.F2_autoreport.create_demands_section(output_JSON_file, sectors=None)¶

This function creates a HTML Div element that holds an entire section with either the demands or the resources

Parameters

output_JSON_file (dict) – Dict with all simulation parameters
sectors (list) – List holding the names of sectors of the energy system as strings Default: None

Returns

Return type

Function call to insert_subsection() that generates the demands section of the autoreport

multi_vector_simulator.F2_autoreport.encode_image_file(img_path)¶

Encode image files to load them in the dash layout under img html tag

Parameters: img_path (str) – path to the image file
Returns: encoded_img – encoded bytes of the image file
Return type: bytes

multi_vector_simulator.F2_autoreport.insert_body_text(body_of_text)¶

This function is for rendering blocks of text within the sub-sections.

Parameters: body_of_text (str) – Typically a single-line or paragraph of text.
Returns: A html element that renders the paragraph of text in the Dash app layout.
Return type: html.P()

multi_vector_simulator.F2_autoreport.insert_headings(heading_text)¶

This function is for creating the headings such as information, input data, etc.

Parameters: heading_text (str) – Big headings for several sub-sections.
Returns: A html element with the heading text encased container.
Return type: html.P()

multi_vector_simulator.F2_autoreport.insert_log_messages(log_dict)¶

This function inserts logging messages that arise during the simulation, such as warnings and error messages, into the auto-report.

Parameters: log_dict (dict) – A dictionary containing the logging messages collected during the simulation.
Returns: This html element holds the children html elements that produce the lists of warnings and error messages for both print and screen versions of the auto-report.
Return type: html.Div()

multi_vector_simulator.F2_autoreport.insert_plotly_figure(fig, id_plot=None, print_only=False)¶

Insert a plotly figure in a dash app layout

Parameters

fig (plotly.graph_objs.Figure) – figure object
id_plot (str) – Id of the graph. Should be unique. Default: None
print_only (bool) – Used to determine if a web version of the plot is to be generated or not. Default: False

Returns

Html Div component containing an image for the print-only version and a plotly figure for the online (no-print) app (in the app the user can interact with plotly figure, whereas the image is static).

Return type

dash_html_components.Div

multi_vector_simulator.F2_autoreport.insert_subsection(title, content, **kwargs)¶

Inserts sub-sections within the Dash app layout, such as Input data, simulation results, etc.

Parameters

title (str) – This is the title or heading of the subsection.
content (list) – This is typically a list of html elements or function calls returning html elements, that make up the body of the sub-section.
kwargs (Any possible optional arguments such as styles, etc.) –

Returns

This returns the sub-section of the report including the tile and other information within the sub-section.

Return type

html.Div()

multi_vector_simulator.F2_autoreport.make_dash_data_table(df, title=None)¶

Function that creates a Dash DataTable from a Pandas dataframe.

Parameters

df (pandas.DataFrame) – This dataframe holds the data from which the dash table is to be created.
title (str) – An optional title for the table. Default: None

Returns

This element contains the title of the dash table and the dash table itself encased in a child html.Div() element.

Return type

html.Div()

multi_vector_simulator.F2_autoreport.open_in_browser(app, timeout=600)¶

Runs the dash app in a thread an open a browser window

Parameters

app (instance of the Dash class, part of the dash library) –
timeout (int or float) – Specifies the number of seconds that the web app should be open in the browser before timing out.

Returns

Return type

Nothing, but the web app version of the auto-report is displayed in a browser.

multi_vector_simulator.F2_autoreport.print_pdf(app=None, path_pdf_report='/home/docs/checkouts/readthedocs.org/user_builds/multi-vector-simulator/checkouts/stable/docs/MVS_outputs/out.pdf')¶

Runs the dash app in a thread and print a pdf before exiting

Parameters

app (instance of the Dash class of the dash library) – Default: None
path_pdf_report (str) – Path where the pdf report should be saved.

Returns

Return type

None, but saves a pdf printout of the provided app under the provided path

multi_vector_simulator.F2_autoreport.ready_capacities_plots(dict_values, only_print=False)¶

Insert the capacities bar plots in a dash html layout

Parameters

dict_values (dict) – Dict with all simulation parameters
only_print (bool) – Setting this value true results in the function creating only the plot for the PDF report, but not the web app version of the auto-report. Default: False

Returns

cap_plots – List containing the capacities bar plots dash components

Return type

list

multi_vector_simulator.F2_autoreport.ready_costs_pie_plots(dict_values, only_print=False)¶

Insert the pie plots in a dash html layout

Parameters

dict_values (dict) – Dict with all simulation parameters
only_print (bool) – Setting this value true results in the function creating only the plot for the PDF report, but not the web app version of the auto-report. Default: False

Returns

pie_plots – List containing the cost pie plots dash components

Return type

list

multi_vector_simulator.F2_autoreport.ready_flows_plots(dict_values, only_print=False)¶

Generate figure for each assets’ flow of the energy system.

Parameters

dict_values (dict) – Dict with all simulation parameters
only_print (bool) – Setting this value true results in the function creating only the plot for the PDF report, but not the web app version of the auto-report. Default: False

Returns

multi_plots – List containing the assets’ timeseries plots as dash components

Return type

list

multi_vector_simulator.F2_autoreport.ready_timeseries_plots(dict_values, data_type='demands', only_print=False, sector_demands=None)¶

Insert the timeseries line plots in a dash html layout.

Parameters

dict_values (dict) – Dict with all simulation parameters
data_type (str) – one of DEMANDS or RESOURCES Default: DEMANDS
only_print (bool) – Setting this value true results in the function creating only the plot for the PDF report, but not the web app version of the auto-report. Default: False
sector_demands (str) – Name of the sector of the energy system Default: None

Returns

plots – List containing the timeseries line plots dash components

Return type

list