Parameters and Definitions in CSVs/JSON¶

List of parameters¶

Below is the list of all the parameters of MVS, sorted in alphabetical order. Each parameter is provided with the definition, unit, type and example values as well to make it easy for users to provide custom values for their systems.

age_installed¶

Definition: The number of years the asset has already been in operation.
Type: Numeric
Unit: Years
Example: 10
Restrictions: Natural numbers
Default: None

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 of total capacity (kWh)
Example: storage capacity: NaN, input power: 1, output power: 1
Restrictions: Only the columns “input power” and “output power” require a value, in column “storage capacity” c_rate should be set to NaN. The C-rate has to be in [0,1].
Default: None

country¶

Definition: Name of the country where the project is being deployed
Type: str
Unit: None
Example: Norway
Restrictions: None
Default: None

currency¶

Definition: The currency of the country where the project is implemented.
Type: str
Unit: None
Example: EUR
Restrictions: None
Default: None

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 numbers
Default: None

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: None
Default: None

dispatch_price¶

Definition: Variable cost associated with a flow through/from the asset (eg. Euro/kWh).
Type: Numeric
Unit: currency/kWh
Example: 0.64
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.
Default: None

dsm¶

Definition: Stands for Demand Side Management. Currently, not implemented.
Type: str
Unit: Boolean value
Example: False
Restrictions: Acceptable values are either True or False.
Default: None

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
Restrictions: Between 0 and 1.
Default: None

emission_factor¶

Definition: Emissions per unit dispatch of an asset.
Type: Numeric
Unit: kgCO2eq/unit
Example: 14.4
Restrictions: Positive real numbers
Default: None

energy_price¶

Definition: Price of energy carrier sourced from the utility grid.
Type: Numeric
Unit: currency/energy carrier unit (for e.g.: Euro/kWh)
Example: 0.1
Restrictions: None
Default: None

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: None
Example: Electricity (or heat, bio-gas, etc.)
Restrictions: None
Default: None

evaluated_period¶

Definition: The number of days for which the simulation is to be run.
Type: Numeric
Unit: Days
Example: 365
Restrictions: None
Default: None

feedin_tariff¶

Definition: Price received for feeding electricity into the grid.
Type: Numeric
Unit: currency/kWh
Example: 0
Restrictions: None
Default: None

file_name¶

Definition: Name of the csv file containing the input PV generation time-series. E.g.: filename.csv
Type: str
Unit: None
Example: demand.csv
Restrictions: None
Default: None

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

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

inflow_direction¶

Definition: The bus/component from which the energyVector is arriving into the asset.
Type: str
Unit: None
Example: Electricity
Restrictions: None
Default: None

installedCap¶

Definition: The already existing installed capacity in-place, which will also be replaced after its lifetime.
Type: Numeric
Unit: kWp
Example: 50
Restrictions: Each component in the energyProduction.csv should have a value.
Default: None

label¶

Definition: Name of the asset
Type: str
Unit: None
Example: Electricity grid DSO
Restrictions: Input the names in a computer readable format, preferably with underscores instead of spaces, and avoiding special characters (eg. pv_plant_01)
Default: None

latitude¶

Definition: Latitude coordinate of the project’s geographical location.
Type: Numeric
Unit: None
Example: 45.641603
Restrictions: Should follow geographical convention
Default: None

lifetime¶

Definition: Number of operational years of the asset until it has to be replaced.
Type: Numeric
Unit: Year
Example: 30
Restrictions: None
Default: None

longitude¶

Definition: Longitude coordinate of the project’s geographical location.
Type: Numeric
Unit: None
Example: 10.95787
Restrictions: Should follow geographical convention
Default: None

maximum_emissions¶

Definition: The maximum amount of total emissions in the optimized energy system.
Type: Numeric or None
Unit: kgCO2eq/a
Example: 100000
Restrictions: Acceptable values are either a positive real number or None
Default: None

maximumCap¶

Definition: The maximum installable capacity.
Type: Alphanumeric
Unit: None or float
Example: 1000
Restrictions: None
Default: None

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: None

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: None

net_zero_energy¶

Definition: Specifies whether optimization needs to result into a net zero energy system (True) or not (False).
Type: str
Unit: Boolean value
Example: True
Restrictions: Acceptable values are either True or False.
Default: False

optimizeCap¶

Definition: True if the user wants to perform capacity optimization for various components as part of the simulation.
Type: str
Unit: Boolean value
Example: True
Restrictions: Permissible values are either True or False
Default: None

outflow_direction¶

Definition: The bus/component to which the energyVector is leaving, from the asset.
Type: str
Unit: None
Example: PV plant (mono)
Restrictions: None
Default: None

output_lp_file¶

Definition: Entering True would result in 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: str
Unit: Boolean
Example: False
Restrictions: Acceptable values are either True or False
Default: None

peak_demand_pricing¶

Definition: Price to be paid additionally for energy-consumption based on the peak demand of a period.
Type: Numeric
Unit: currency/kW
Example: 60
Restrictions: None
Default: None

Peak_demand_pricing_period¶

Definition: Number of reference periods in one year for the peak demand pricing. Only one of the following are acceptable values: 1 (yearly), 2, 3 ,4, 6, 12 (monthly).
Type: Numeric
Unit: times per year (1,2,3,4,6,12)
Example: 2
Restrictions: Should be one of the following values: 1,2,3,4,6, or 12
Default: None

Project_duration¶

Definition: The name 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: None
Default: None

Project_id¶

Definition: Users can assign a project ID as per their preference.
Type: Alphanumeric
Unit: None
Example: 1
Restrictions: None
Default: None

Project_name¶

Definition: Users can assign a project name as per their preference.
Type: Alphanumeric
Unit: None
Example: Borg Havn
Restrictions: None
Default: None

renewableAsset¶

Definition: User can enter True if the asset is considered as a renewable energy source. False should be entered otherwise.
Type: str
Unit: Boolean
Example: True
Restrictions: Acceptable values are either True or False
Default: None

scenario_description¶

Definition: Brief description of the scenario being simulated.
Type: Alphanumeric
Unit: None
Example: This scenario similated a sector-coupled energy system
Restrictions: None
Default: None

scenario_id¶

Definition: Users can assign a scenario id as per their preference.
Type: Alphanumeric
Unit: None
Example: 1
Restrictions: None
Default: None

scenario_name¶

Definition: Users can assign a scenario name as per their preference.
Type: Alphanumeric
Unit: None
Example: Warehouse 14
Restrictions: None
Default: None

soc_initial¶

Definition: The level of charge (as a factor of the actual capacity) in the storage in the zeroth time-step.
Type: Numeric
Unit: None or factor
Example: storage capacity: None, input 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.
Default: None

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: 1
Restrictions: Only the column “storage capacity” requires a value, in column “input power” and “output power” soc_max should be set to NaN.
Default: None

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: 0.2
Restrictions: Only the column “storage capacity” requires a value, in column “input power” and “output power” soc_min should be set to NaN.
Default: None

specific_costs¶

Definition: Actual CAPEX of the asset, i.e., specific investment costs
Type: Numeric
Unit: currency/unit (e.g.: Euro/kW)
Example: 4000
Restrictions: None
Default: None

specific_costs_om¶

Definition: Actual OPEX of the asset, i.e., specific operational and maintenance costs.
Type: Numeric
Unit: currency/unit/year
Example: 0
Restrictions: None
Default: None

start_date¶

Definition: The data and time on which the simulation starts at the first step.
Type: str
Unit: None
Example: 2018-01-01 00:00:00
Restrictions: Acceptable format is YYYY-MM-DD HH:MM:SS
Default: None

storage_filename¶

Definition: Corresponding to the values in C1, D1, E1… cells, enter the correct CSV filename which hosts the parameters of the corresponding storage component.
Type: str
Unit: None
Example: storage_01.csv
Restrictions: Follows the convention of ‘storage_xx.csv’ where ‘xx’ is a number
Default: None

tax¶

Definition: Tax factor.
Type: Numeric
Unit: Factor
Example: 0
Restrictions: None
Default: None

timestep¶

Definition: Length of the time-steps.
Type: Numeric
Unit: Minutes
Example: 60
Restrictions: None
Default: None

type_asset¶

Definition: The type of the component.
Type: str
Unit: None
Example: demand
Restrictions: demand
Default: None

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: None
Example: sink
Restrictions: sink or source or one of the other component classes of OEMOF.
Default: None

unit¶

Definition: Unit associated with the capacity of the component.
Type: str
Unit: NA
Example: Storage could have units like kW or kWh, transformer station could have kVA, and so on.
Restrictions: Appropriate scientific unit
Default: None

Parameters in each 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 heads.

constraints.csv¶

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

minimal_renewable_factor
maximum_emissions
minimal_degree_of_autonomy
net_zero_energy

economic_data.csv¶

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

currency
Project_duration
discount_factor
tax

eneryBusses.csv¶

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

energyVector

energyConsumption.csv¶

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

unit
inflow_direction
energyVector
file_name
type_asset
type_oemof
dsm

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:

unit
optimizeCap
installedCap
age_installed
lifetime
development_costs
specific_costs
specific_costs_om
dispatch_price
efficiency
inflow_direction
outflow_direction
energyVector
type_oemof

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:

unit
optimizeCap
maximumCap
installedCap
age_installed
lifetime
development_costs
specific_costs
specific_costs_om
dispatch_price
outflow_direction
file_name
energyVector
renewableAsset
emission_factor
type_oemof

energyProviders.csv¶

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

unit
optimizeCap
energy_price
feedin_tariff
peak_demand_pricing
Peak_demand_pricing_period
renewable_share
inflow_direction
outflow_direction
energyVector
emission_factor
type_oemof

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:

optimizeCap
inflow_direction
outflow_direction
storage_filename
energyVector
type_oemof

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:

label
age_installed
lifetime
development_costs
specific_costs
specific_costs_om
dispatch_price

project_data.csv¶

The file project_data.csv includes the following parameters:

country
latitude
longitude
Project_id
Project_name
scenario_id
scenario_name
scenario_description

simulation_settings.csv¶

The file simulation_settings.csv includes the following parameters:

start_date
evaluated_period
timestep
output_lp_file

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:

unit
installedCap
age_installed
lifetime
development_costs
specific_costs
specific_costs_om
dispatch_price
c-rate
efficiency
soc_initial
soc_max
soc_min