Input parameters

Parameters in each category/CSV file

Important note: Each asset and bus needs to have an unique label. In the csv input files, these are defined by the column headers. The input parameters are gathered under the following categories. These categories reflect the structure of the csv input files or the firsts keys of the json input file.

constraints.csv

The file constraints.csv includes the following parameter(s):

economic_data.csv

The file economic_data.csv includes all economic data that the simulation will use. This includes the following parameters:

energyBusses.csv

The file energyBusses.csv defines all busses required to build the energy system. It includes following parameters:

energyConsumption.csv

The file energyConsumption.csv defines all energy demands that should be included in the energy system. It includes the following parameters:

energyConversion.csv

The file energyConversion.csv defines the assets that convert one energy carrier into another one, eg. inverters or generators. Following parameters define them:

energyProduction.csv

The file energyProduction.csv defines the assets that serve as energy sources, eg. fuel sources or PV plants. They include the following parameters:

energyProviders.csv

The file energyProviders.csv defines the energy providers of the energy system. They include the following parameters:

energyStorage.csv

The file energyStorage.csv defines the storage assets included in the energy system. It does not hold all needed parameters, but requires storage_xx.csv to be defined as well. The file energyStorage.csv includes the following parameters:

fixcost.csv

The parameters must be filled for all three columns/components namely: distribution_grid, engineering and operation. The file fixcost.csv includes the following parameters:

project_data.csv

The file project_data.csv includes the following parameters:

simulation_settings.csv

The file simulation_settings.csv includes the following parameters:

storage_*.csv

The * in the storage filename is the number identifying the storage. It depends on the number of storage components (such as batteries, etc.) present in the system. For e.g., there should be two storage files named storage_01.csv and storage_02.csv if the system contains two storage components.The file storage_xx.csv contains the following parameters:

Table of parameters

The input parameters are gathered in the table below. Each parameter is provided with unit, type and example values. For more information about one parameter, please click on it.

Parameters summary

Parameter

Type

Unit

Default

age_installed

numeric

Year

0

c-rate

numeric

Factor

1

country

str

currency

str

EUR

development_costs

numeric

currency

0

discount_factor

numeric

Factor

0

dispatch_price

numeric

currency/kWh

0

efficiency

numeric

Factor

1

emission_factor

numeric

kgCO2eq/asset unit

0

energy_price

numeric

currency/energy carrier unit

0

energyVector

str

Electricity

evaluated_period

numeric

Day

365

feedin_tariff

numeric

currency/kWh

0

file_name

str

fixed_thermal_losses_absolute

numeric

factor

0

fixed_thermal_losses_relative

numeric

factor

0

inflow_direction

str

installedCap

numeric

kWp

0

label

str

latitude

numeric

lifetime

numeric

Year

20

longitude

numeric

maximum_emissions

numeric

kgCO2eq/a

maximumCap

numeric

kWp

minimal_degree_of_autonomy

numeric

factor

0

minimal_renewable_factor

numeric

factor

0

net_zero_energy

boolean

False

optimizeCap

boolean

False

outflow_direction

str

output_lp_file

boolean

False

peak_demand_pricing

numeric

currency/kW

0

peak_demand_pricing_period

numeric

times per year (1,2,3,4,6,12)

1

project_duration

numeric

Years

20

project_id

str

project_name

str

renewable_share

numeric

Factor

0

renewableAsset

boolean

False

scenario_description

str

scenario_id

str

scenario_name

str

soc_initial

numeric

None or factor

soc_max

numeric

Factor

1

soc_min

numeric

Factor

0

specific_costs

numeric

currency/unit

0

specific_costs_om

numeric

currency/unit/year

0

start_date

str

storage_filename

str

tax

numeric

Factor

0

timestep

numeric

Minutes

60

type_oemof

str

unit

str

beta

numeric

factor

0

List of parameters

Below is the list of all the parameters of MVS, sorted in alphabetical order. Each of the parameters has the following properties

Definition:

parameter’s definition, could also contain potential use cases of the parameter

Type:

str (text), numeric (integer or double precision number), boolean (True or False)

Unit:

physical unit

Example:

an example of parameter’s value

Restrictions:

specific restrictions on the parameter’s value (e.g., “positive integer number”, “must be an even number”, “must be one of [‘val1’, ‘val2’]”

Default:

default parameter’s value

age_installed

Definition:

The number of years the asset has already been in operation.

Type:

numeric

Unit:

Year

Example:

10

Restrictions:

Natural number

Default:

0

This parameter is used within the following categories: energyConversion.csv, energyProduction.csv

c-rate

Definition:

C-rate is the rate at which the storage can charge or discharge relative to the nominal capacity of the storage. A c-rate of 1 implies that the battery can discharge or charge completely in a single timestep.

Type:

numeric

Unit:

Factor

Example:

storage capacity: NaN, input power: 1, output power: 1

Restrictions:

Real number between 0 and 1. Only the columns “input power” and “output power” require a value, in column “storage capacity” c_rate should be set to NaN.

Default:

1

This parameter is used within the following categories: storage_*.csv

country

Definition:

Name of the country where the project is being deployed

Type:

str

Unit:

nan

Example:

Norway

Restrictions:

nan

Default:

nan

This parameter is used within the following categories: project_data.csv

currency

Definition:

The currency of the country where the project is implemented.

Type:

str

Unit:

nan

Example:

EUR

Restrictions:

nan

Default:

EUR

This parameter is used within the following categories: economic_data.csv

development_costs

Definition:

A fixed cost to implement the asset, eg. planning costs which do not depend on the (optimized) asset capacity.

Type:

numeric

Unit:

currency

Example:

10000

Restrictions:

Positive real number

Default:

0

This parameter is used within the following categories: energyConversion.csv, storage_*.csv, energyProduction.csv, fixcost.csv

discount_factor

Definition:

Discount factor is the factor which accounts for the depreciation in the value of money in the future, compared to the current value of the same money. The common method is to calculate the weighted average cost of capital (WACC) and use it as the discount rate.

Type:

numeric

Unit:

Factor

Example:

0.06

Restrictions:

Between 0 and 1

Default:

0

This parameter is used within the following categories: economic_data.csv

dispatch_price

Definition:

Variable cost associated with a flow through/from the asset (eg. Euro/kWh).

Type:

numeric

Unit:

currency/kWh

Example:

0.64 or “[0.3, 0.26]” for multiple input or output busses

Restrictions:

In “storage_xx.csv” only the columns “input power” and “output power” require a value, in column “storage capacity” dispatch_price should be set to NaN. In conversion assets, there should be different dispatch prices provided for each input or output busses. For two output busses (for example a heat pump), then write “[0.1, 0.4]”

Default:

0

This parameter is used within the following categories: energyConversion.csv, energyProduction.csv, storage_*.csv, fixcost.csv

efficiency

Definition:

Ratio of energy output/energy input. The battery efficiency is the ratio of the energy taken out from the battery, to the energy put into the battery. It means that it is not possible to retrieve as much energy as provided to the battery due to the discharge losses. The efficiency of the “input power” and “ouput power” columns should be set equal to the charge and dischage efficiencies respectively, while the “storage capacity” efficiency should be equal to the storage’s efficiency/ability to hold charge over time (= 1 - self-discharge/decay), which is usually in the range of 0.95 to 1 for electrical storages.

Type:

numeric

Unit:

Factor

Example:

0.95 or “[0.91, 0.98]” for multiple input or output busses

Restrictions:

Between 0 and 1

Default:

1

This parameter is used within the following categories: energyConversion.csv, storage_*.csv

emission_factor

Definition:

Emissions per unit dispatch of an asset.

Type:

numeric

Unit:

kgCO2eq/asset unit

Example:

14.4

Restrictions:

Positive real number

Default:

0

This parameter is used within the following categories: energyProviders.csv, energyProduction.csv

energy_price

Definition:

Price of energy carrier sourced from the utility grid.

Type:

numeric

Unit:

currency/energy carrier unit

Example:

0.1

Restrictions:

nan

Default:

0

This parameter is used within the following categories: energyProviders.csv

energyVector

Definition:

Energy vector/commodity. Convention: For an energy conversion asset define energyVector of the output. For a sink define based on inflow. For a source define based on output flow. For a storage, define based on stored energy carrier.

Type:

str

Unit:

nan

Example:

Electricity

Restrictions:

One of “Electricity”, “Gas”, “Bio-Gas”, “Diesel”, “Heat”, “H2”

Default:

Electricity

This parameter is used within the following categories: energyBusses.csv, energyConsumption.csv, energyProduction.csv, energyStorage.csv, energyProviders.csv, energyConversion.csv

evaluated_period

Definition:

The number of days simulated with the energy system model.

Type:

numeric

Unit:

Day

Example:

365

Restrictions:

Natural number

Default:

365

This parameter is used within the following categories: simulation_settings.csv

feedin_tariff

Definition:

Price received for feeding electricity into the grid.

Type:

numeric

Unit:

currency/kWh

Example:

0.7

Restrictions:

Real number between 0 and 1

Default:

0

This parameter is used within the following categories: energyProviders.csv

file_name

Definition:

Name of a csv file containing the input generation or demand timeseries.

Type:

str

Unit:

nan

Example:

demand_harbor.csv

Restrictions:

This file must be placed in a folder named “time_series” inside your input folder.

Default:

nan

This parameter is used within the following categories: energyConsumption.csv, energyProduction.csv, energyStorage.csv

fixed_thermal_losses_absolute

Definition:

Thermal losses of storage independent of state of charge and independent of nominal storage capacity between two consecutive timesteps.

Type:

numeric

Unit:

factor

Example:

0.0003

Restrictions:

Between 0 and 1

Default:

0

This parameter is used within the following categories: storage_*.csv

fixed_thermal_losses_relative

Definition:

Thermal losses of storage independent of state of charge between two consecutive timesteps relative to nominal storage capacity.

Type:

numeric

Unit:

factor

Example:

0.0016

Restrictions:

Between 0 and 1

Default:

0

This parameter is used within the following categories: storage_*.csv

inflow_direction

Definition:

The label of the bus/component from which the energyVector is arriving into the asset.

Type:

str

Unit:

nan

Example:

Electricity or “[Electricity, Heat]” for multiple input busses

Restrictions:

nan

Default:

nan

This parameter is used within the following categories: energyConsumption.csv, energyConversion.csv, energyProviders.csv, energyStorage.csv

installedCap

Definition:

The already existing installed capacity in-place. If the project lasts longer than its remaining lifetime, its replacement costs will be taken into account.

Type:

numeric

Unit:

kWp

Example:

50

Restrictions:

Each component in the “energy production” category must have a value.

Default:

0

This parameter is used within the following categories: energyConversion.csv, energyProduction.csv, storage_*.csv

label

Definition:

Name of the asset for display purposes

Type:

str

Unit:

nan

Example:

pv_plant_01

Restrictions:

Input the names in a computer friendly format, preferably with underscores instead of spaces, and avoiding special characters

Default:

nan

This parameter is used within the following categories: fixcost.csv

latitude

Definition:

Latitude coordinate of the project’s geographical location.

Type:

numeric

Unit:

nan

Example:

45.641603

Restrictions:

Should follow geographical convention

Default:

nan

This parameter is used within the following categories: project_data.csv

lifetime

Definition:

Number of operational years of the asset until it has to be replaced.

Type:

numeric

Unit:

Year

Example:

30

Restrictions:

Natural number

Default:

20

This parameter is used within the following categories: energyConversion.csv, energyProduction.csv, storage_*.csv, fixcost.csv

longitude

Definition:

Longitude coordinate of the project’s geographical location.

Type:

numeric

Unit:

nan

Example:

10.95787

Restrictions:

Should follow geographical convention

Default:

nan

This parameter is used within the following categories: project_data.csv

maximum_emissions

Definition:

The maximum amount of total emissions in the optimized energy system.

Type:

numeric

Unit:

kgCO2eq/a

Example:

100000

Restrictions:

Acceptable values are either a positive real number or None

Default:

nan

This parameter is used within the following categories: constraints.csv

maximumCap

Definition:

The maximum total capacity of an asset that can be installed at the project site. This includes the installed and the also the maximum additional capacity possible. An example would be that a roof can only carry 50 kWp PV (maximumCap), whereas the installed capacity is already 10 kWp. The optimization would only be allowed to add 40 kWp PV at maximum.

Type:

numeric

Unit:

kWp

Example:

1050

Restrictions:

Acceptable values are either a positive real number or None

Default:

nan

This parameter is used within the following categories: energyProduction.csv

minimal_degree_of_autonomy

Definition:

The minimal degree of autonomy that needs to be met by the optimization.

Type:

numeric

Unit:

factor

Example:

0.3

Restrictions:

Between 0 and 1

Default:

0

This parameter is used within the following categories: constraints.csv

minimal_renewable_factor

Definition:

The minimum share of energy supplied by renewable generation in the optimized energy system. Insert the value 0 to deactivate this constraint.

Type:

numeric

Unit:

factor

Example:

0.7

Restrictions:

Between 0 and 1

Default:

0

This parameter is used within the following categories: constraints.csv

net_zero_energy

Definition:

Specifies whether optimization needs to result into a net zero energy system (True) or not (False).

Type:

boolean

Unit:

nan

Example:

True

Restrictions:

Acceptable values are either True or False.

Default:

False

This parameter is used within the following categories: constraints.csv

optimizeCap

Definition:

Allow the user to perform capacity optimization for an asset.

Type:

boolean

Unit:

nan

Example:

True

Restrictions:

Permissible values are either True or False

Default:

False

This parameter is used within the following categories: energyConversion.csv, energyProduction.csv, energyProviders.csv, energyStorage.csv

outflow_direction

Definition:

The label of bus/component towards which the energyVector is leaving from the asset.

Type:

str

Unit:

nan

Example:

Electricity or “[Electricity, Heat]” for multiple output busses

Restrictions:

nan

Default:

nan

This parameter is used within the following categories: energyConsumption.csv, energyConversion.csv, energyProviders.csv, energyStorage.csv

output_lp_file

Definition:

Enable the generation of a file with the linear equation system describing the simulation, ie., with the objective function and all the constraints. This lp file enables the user look at the underlying equations of the optimization.

Type:

boolean

Unit:

nan

Example:

False

Restrictions:

Acceptable values are either True or False

Default:

False

This parameter is used within the following categories: simulation_settings.csv

peak_demand_pricing

Definition:

Price to be paid additionally for energy-consumption based on the peak demand of a given period.

Type:

numeric

Unit:

currency/kW

Example:

60

Restrictions:

nan

Default:

0

This parameter is used within the following categories: energyProviders.csv

See also: peak_demand_pricing_period

peak_demand_pricing_period

Definition:

Number of reference periods in one year for the peak demand pricing.

Type:

numeric

Unit:

times per year (1,2,3,4,6,12)

Example:

2

Restrictions:

Only one of the following are acceptable values: 1 (yearly), 2, 3 ,4, 6, 12 (monthly)

Default:

1

This parameter is used within the following categories: energyProviders.csv

See also: peak_demand_pricing

project_duration

Definition:

The number of years the project is intended to be operational. The project duration also sets the installation time of the assets used in the simulation. After the project ends these assets are ‘sold’ and the refund is charged against the initial investment costs.

Type:

numeric

Unit:

Years

Example:

30

Restrictions:

Natural number

Default:

20

This parameter is used within the following categories: economic_data.csv

project_id

Definition:

Users can assign a project ID as per their preference.

Type:

str

Unit:

nan

Example:

1

Restrictions:

Cannot be the same as an already existing project

Default:

nan

This parameter is used within the following categories: project_data.csv

project_name

Definition:

Users can assign a project name as per their preference.

Type:

str

Unit:

nan

Example:

Borg Havn

Restrictions:

nan

Default:

nan

This parameter is used within the following categories: project_data.csv

renewable_share

Definition:

The share of renewables in the generation mix of the energy supplied by the DSO (utility).

Type:

numeric

Unit:

Factor

Example:

0.1

Restrictions:

Real number between 0 and 1

Default:

0

This parameter is used within the following categories: energyProviders.csv

renewableAsset

Definition:

Allow the user to tag as asset as renewable.

Type:

boolean

Unit:

nan

Example:

True

Restrictions:

Acceptable values are either True or False

Default:

False

This parameter is used within the following categories: energyProduction.csv

scenario_description

Definition:

Brief description of the scenario being simulated.

Type:

str

Unit:

nan

Example:

This scenario simulates a sector-coupled energy system

Restrictions:

nan

Default:

nan

This parameter is used within the following categories: project_data.csv

scenario_id

Definition:

Users can assign a scenario id as per their preference.

Type:

str

Unit:

nan

Example:

1

Restrictions:

Cannot be the same as an already existing scenario within the project

Default:

nan

This parameter is used within the following categories: project_data.csv

scenario_name

Definition:

Users can assign a scenario name as per their preference.

Type:

str

Unit:

nan

Example:

Warehouse 14

Restrictions:

nan

Default:

nan

This parameter is used within the following categories: project_data.csv

soc_initial

Definition:

The level of charge (as a factor of the actual capacity) in the storage in the initial (0) time-step.

Type:

numeric

Unit:

None or factor

Example:

storage capacity: None, input power: NaN, output power: NaN

Restrictions:

Acceptable values are either None or the factor. Only the column storage capacity requires a value, in column input power and output power soc_initial should be set to NaN. The soc_initial has to be within the [0,1] interval.

Default:

nan

This parameter is used within the following categories: storage_*.csv

soc_max

Definition:

The maximum permissible level of charge in the battery (generally, it is when the battery is filled to its nominal capacity), represented by the value 1.0. Users can also specify a certain value as a factor of the actual capacity.

Type:

numeric

Unit:

Factor

Example:

storage capacity: 1, input power: NaN, output power: NaN

Restrictions:

Only the column storage capacity requires a value, in column input power and output power soc_max should be set to NaN. The soc_max has to be in the [0,1] interval.

Default:

1

This parameter is used within the following categories: storage_*.csv

soc_min

Definition:

The minimum permissible level of charge in the battery as a factor of the nominal capacity of the battery.

Type:

numeric

Unit:

Factor

Example:

storage capacity:0.2, input power: NaN, output power: NaN

Restrictions:

Only the column storage capacity requires a value, in column input power and output power soc_min should be set to NaN. The soc_min has to be in the [0,1] interval.

Default:

0

This parameter is used within the following categories: storage_*.csv

specific_costs

Definition:

Actual CAPEX of an asset, i.e., specific investment costs

Type:

numeric

Unit:

currency/unit

Example:

4000

Restrictions:

nan

Default:

0

This parameter is used within the following categories: energyConversion.csv, energyProduction.csv, storage_*.csv, fixcost.csv

specific_costs_om

Definition:

Actual OPEX of an asset, i.e., specific operational and maintenance costs.

Type:

numeric

Unit:

currency/unit/year

Example:

120

Restrictions:

nan

Default:

0

This parameter is used within the following categories: energyConversion.csv, energyProduction.csv, storage_*.csv, fixcost.csv

start_date

Definition:

The date and time on which the simulation starts at the first step.

Type:

str

Unit:

nan

Example:

2018-01-01 00:00:00

Restrictions:

Acceptable format is YYYY-MM-DD HH:MM:SS

Default:

nan

This parameter is used within the following categories: simulation_settings.csv

storage_filename

Definition:

Name of a csv file containing the properties of a storage component

Type:

str

Unit:

nan

Example:

storage_01.csv

Restrictions:

Follows the convention of ‘storage_xx.csv’ where ‘xx’ is a number. This file must be placed in a folder named “csv_elements” inside your input folder.

Default:

nan

This parameter is used within the following categories: energyStorage.csv

tax

Definition:

Tax factor.

Type:

numeric

Unit:

Factor

Example:

0

Restrictions:

Between 0 and 1

Default:

0

This parameter is used within the following categories: economic_data.csv

timestep

Definition:

Length of the time-steps.

Type:

numeric

Unit:

Minutes

Example:

60

Restrictions:

Can only be 60 at the moment

Default:

60

This parameter is used within the following categories: simulation_settings.csv

type_oemof

Definition:

Input the type of OEMOF component. For example, a PV plant would be a source, a solar inverter would be a transformer, etc. The type_oemof will later on be determined through the EPA.

Type:

str

Unit:

nan

Example:

sink

Restrictions:

sink or source or one of the other component classes of OEMOF.

Default:

nan

This parameter is used within the following categories: energyConsumption.csv, energyConversion.csv, energyProduction.csv, energyProviders.csv, energyStorage.csv

unit

Definition:

Unit associated with the capacity of the component.

Type:

str

Unit:

nan

Example:

Storage could have units like kW or kWh, transformer station could have kVA, and so on.

Restrictions:

Appropriate scientific unit

Default:

nan

This parameter is used within the following categories: energyConsumption.csv, energyConversion.csv, energyProduction.csv, energyProviders.csv, storage_*.csv

beta

Definition:

Power loss index for CHPs

Type:

numeric

Unit:

factor

Example:

0.6

Restrictions:

Between 0 and 1

Default:

0

This parameter is used within the following categories: energyConversion.csv