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 is set to False by default
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
NET_ZERO_ENERGY: False
- 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.get_item_if_list(list_or_float, index)¶
- multi_vector_simulator.utils.helpers.get_length_if_list(list_or_float)¶
- multi_vector_simulator.utils.helpers.peak_demand_bus_name(dso_name: str, feedin: bool = False)¶
Name for auto created bus related to peak demand pricing period
- multi_vector_simulator.utils.helpers.peak_demand_transformer_name(dso_name: str, peak_number: Optional[int] = None, feedin: bool = False)¶
Name for auto created bus related to peak demand pricing period
- 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
- 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
- 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
- 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]
- 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
- 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
- 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
- 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_name)¶
Defines all sinks and sources that need to be added to model the transformer using assets of energyConsumption, energyProduction and energyConversion.
- Parameters
dict_values (dict) – All simulation parameters
dso_name (str) – the name of the energy provider asset
- 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
- 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
- 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.
- 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 –
asset (dictionary of the) –
file_name –
series (name of the file to read the time) –
header –
provided (name of the column where the timeseries is) –
- 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()
- 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
- 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
- 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
- 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
- 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.
with 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.
- 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
- 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
- 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
- Return type
None
- plot_sankey_diagramm(model, save_energy_system_graph=False)¶
Prepare a sankey diagram of the simulated energy model
- 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
- 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
- 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
- Return type
Nothing.
- multi_vector_simulator.D0_modelling_and_optimization.run_oemof(dict_values, save_energy_system_graph=False, return_les=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.
save_energy_system_graph (bool) – if set to True, saves a local copy of the energy system’s graph
return_les (bool) – if set to True, the return also includes the local_energy_system in third position
- 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
- 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
- class multi_vector_simulator.D1_model_components.CustomBus(*args, **kwargs)¶
- 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.
oemof (Required are busses and a dictionary belonging to the respective) –
asset. (type of the) –
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.chp(model, dict_asset, **kwargs)¶
Defines a chp component specified in dict_asset.
Depending on the ‘value’ of ‘optimizeCap’ in dict_asset the chp is defined with a fixed capacity or a capacity to be optimized. The chp has single input and multiple output busses.
- Parameters
model (oemof.solph.network.EnergySystem object) – See the oemof documentation for more information.
dict_asset (dict) – Contains information about the chp like (not exhaustive): efficiency, installed capacity (‘installedCap’), information on the busses the chp is connected to (‘inflow_direction’, ‘outflow_direction’), beta coefficient.
busses (dict) –
sinks (dict, optional) –
sources (dict, optional) –
transformers (dict) –
storages (dict, optional) –
extractionTurbineCHP (dict, optional) –
Notes
The transformer has either multiple input or multiple output busses.
The following functions are used for defining the chp: *
chp_fix()
*chp_optimize()
for investment optimizationTested with: - test_chp_fix_cap() - test_chp_optimize_cap() - test_chp_missing_beta() - test_chp_wrong_beta_formatting() - test_chp_wrong_efficiency_formatting() - test_chp_wrong_outflow_bus_energy_vector()
- Return type
Indirectly updated model and dict of asset in kwargs with chp object.
- multi_vector_simulator.D1_model_components.chp_fix(model, dict_asset, **kwargs)¶
Extraction turbine chp from Oemof solph. Extraction turbine must have one input and two outputs .. rubric:: Notes
Tested with: - test_to_be_written()
- Return type
Indirectly updated model and dict of asset in kwargs with the extraction turbine component.
- multi_vector_simulator.D1_model_components.chp_optimize(model, dict_asset, **kwargs)¶
Extraction turbine chp from Oemof solph. Extraction turbine must have one input and two outputs .. rubric:: Notes
Tested with: - test_to_be_written()
- Return type
Indirectly updated model and dict of asset in kwargs with the extraction turbine component.
- 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()
- 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()
- 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 (* We should actually not allow multiple output) –
sinks (dict) –
sources (dict, optional) –
transformers (dict, optional) –
storages (dict, optional) –
TODOS –
^^^^^ –
busses –
then (probably - because a pv would) –
example (feed in twice as much as solar_gen_specific for) –
#121 (see issue) –
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()
- 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()
- 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()
- 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()
- 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()
- 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()
- 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()
- 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()
- 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:
Tested with: - Test_Constraints.test_benchmark_minimal_degree_of_autonomy()
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:
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:
Tested with: - Test_Constraints.test_net_zero_energy_constraint()
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
- 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
- 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.
- 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, bus_name=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”.
bus_name (str or None) – The name of the current bus (for asset connected to more than one bus)
- 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
- 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
- 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
- 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
- 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
- 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, multi_bus=None)¶
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
multi_bus (str or None) – The name of the current bus (for asset connected to more than one bus)
- 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
- 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
- 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.
- 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) –
Specific per-unit investment costs of an asset over its lifetime, including all replacement costs
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) –
specific operation and management costs per unit in year 0
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) –
operation and management expenditures per annum for the installed capacity
operation and management expenditures for whole project lifetime for the installed capacity
dispatch_expenditures (float) –
dispatch expenditures per annum for the installed capacity
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
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()
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() - E3.test_add_total_consumption_from_provider_electricity_equivalent_two_providers_one_energy_carrier
- 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()
- test_add_total_feedin_electricity_equivalent_two_providers_one_energy_carrier
- 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
- 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 : 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:
The LCOE sets these attributed costs in relation to the energy carrier demand (in its original unit):
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()
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:
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
- Return type
Updates the results dictionary with the log messages of the simulation
Notes
This function is tested with: - test_F0_output.TestLogCreation.test_parse_simulation_log
- 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
- sankey(results)¶
Return a dict to a plotly sankey diagram
- 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 flowx_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
- 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
- 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
- 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_sankey(dict_values)¶
- 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
- 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
- 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
- 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 objectid_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.
- 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/latest/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.
- 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_sankey_diagram(dict_values, only_print=False)¶
- 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