API Reference

oemof.tabular.datapackage package

Submodules

oemof.tabular.datapackage.aggregation module

Module used for aggregation sequences and elements.

oemof.tabular.datapackage.aggregation.temporal_clustering(datapackage, n, path='/tmp', how='daily')[source]

Creates a new datapackage by aggregating sequences inside the sequence folder of the specified datapackage by clustering n timesteps

Parameters:
  • datapackage (string) – String of meta data file datapackage.json
  • n (integer) – Number of clusters
  • path (string) – Path to directory where the aggregated datapackage is stored
  • how (string) – How to cluster ‘daily’ or ‘hourly’
oemof.tabular.datapackage.aggregation.temporal_skip(datapackage, n, path='/tmp', name=None, *args)[source]

Creates a new datapackage by aggregating sequences inside the sequence folder of the specified datapackage by skipping n timesteps

Parameters:
  • datapackage (string) – String of meta data file datapackage.json
  • n (integer) – Number of timesteps to skip
  • path (string) – Path to directory where the aggregated datapackage is stored
  • name (string) – Name of the new, aggregated datapackage. If not specified a name will be given

oemof.tabular.datapackage.building module

oemof.tabular.datapackage.building.download_data(url, directory='cache', unzip_file=None, **kwargs)[source]

Downloads data and stores it in specified directory

Parameters:
  • url (str) – Url of file to be downloaded.
  • directory (str) – Name of directory where to store the downloaded data. Default is ‘cache’-
  • unzip_file (str) – Regular or directory file name to be extracted from zip source.
  • kwargs – Additional keyword arguments.
oemof.tabular.datapackage.building.infer_metadata(package_name='default-name', keep_resources=False, foreign_keys=None, path=None, metadata_filename='datapackage.json')[source]

Add basic meta data for a datapackage

Parameters:
  • package_name (string) – Name of the data package
  • keep_resources (boolean) – Flag indicating of the resources meta data json-files should be kept after main datapackage.json is created. The resource meta data will be stored in the resources directory.
  • foreign_keys (dict) – Dictionary with foreign key specification. Keys for dictionary are: ‘bus’, ‘profile’, ‘from_to_bus’. Values are list with strings with the name of the resources
  • path (string) – Absolute path to root-folder of the datapackage
  • metadata_filename (basestring) – Name of the inferred metadata string.
oemof.tabular.datapackage.building.infer_resources(directory='data/elements')[source]

Method looks at all files in directory and creates datapackage.Resource object that will be stored

Parameters:directory (string) – Path to directory from where resources are inferred
oemof.tabular.datapackage.building.initialize(config, directory='.')[source]

Initialize datapackage by reading config file and creating required directories (data/elements, data/sequences etc.) if directories are not specified in the config file, the default directory setup up will be used.

oemof.tabular.datapackage.building.input_filepath(file, directory='archive/')[source]
oemof.tabular.datapackage.building.package_from_resources(resource_path, output_path, clean=True)[source]

Collects resource descriptors and merges them in a datapackage.json

Parameters:
  • resource_path (string) – Path to directory with resources (in .json format)
  • output_path (string) – Root path of datapackage where the newly created datapckage.json is stored
  • clean (boolean) – If true, resources will be deleted
oemof.tabular.datapackage.building.read_build_config(file='build.toml')[source]

Read config build file in toml format

Parameters:file (string) – String with name of config file
oemof.tabular.datapackage.building.read_elements(filename, directory='data/elements')[source]

Reads element resources from the datapackage

Parameters:
  • filename (string) – Name of the elements to be read, for example load.csv
  • directory (string) – Directory where the file is located. Default: data/elements
Returns:

pd.DataFrame
oemof.tabular.datapackage.building.read_sequences(filename, directory='data/sequences')[source]

Reads sequence resources from the datapackage

Parameters:
  • filename (string) – Name of the sequences to be read, for example load_profile.csv
  • directory (string) – Directory from where the file should be read. Default: data/sequences
oemof.tabular.datapackage.building.timeindex(year, periods=8760, freq='H')[source]

Create pandas datetimeindex.

Parameters:
  • year (string) – Year of the index
  • periods (string) – Number of periods, default: 8760
  • freq (string) – Freq of the datetimeindex, default: ‘H’
oemof.tabular.datapackage.building.update_package_descriptor()[source]
oemof.tabular.datapackage.building.write_elements(filename, elements, directory='data/elements', replace=False, overwrite=False, create_dir=True)[source]

Writes elements to filesystem.

Parameters:
  • filename (string) – Name of the elements to be read, for example reservoir.csv
  • elements (pd.DataFrame) – Elements to be stored in data frame. Index: name
  • directory (string) – Directory where the file is stored. Default: data/elements
  • replace (boolean) – If set, existing data will be overwritten. Otherwise integrity of data (unique indices) will be checked
  • overwrite (boolean) – If set, existing elements will be overwritten
  • create_dir (boolean) – Create the directory if not exists
Returns:

path (string) – Returns the path where the file has been stored.
oemof.tabular.datapackage.building.write_sequences(filename, sequences, directory='data/sequences', replace=False, create_dir=True)[source]

Writes sequences to filesystem.

Parameters:
  • filename (string) – Name of the sequences to be read, for example load_profile.csv
  • sequences (pd.DataFrame) – Sequences to be stored in data frame. Index: datetimeindex with format %Y-%m-%dT%H:%M:%SZ
  • directory (string) – Directory where the file is stored. Default: data/elements
  • replace (boolean) – If set, existing data will be overwritten. Otherwise integrity of data (unique indices) will be checked
  • create_dir (boolean) – Create the directory if not exists
Returns:

path (string) – Returns the path where the file has been stored.

oemof.tabular.datapackage.processing module

oemof.tabular.datapackage.processing.clean(path=None, directories=['data', 'cache', 'resources'])[source]
Parameters:
  • path (str) – Path to root directory of the datapackage, if no path is passed the current directory is to be assumed the root.
  • directories (list (optional)) – List of directory names inside the root directory to clean (remove).
oemof.tabular.datapackage.processing.copy_datapackage(source, destination, subset=None)[source]
Parameters:
  • source (str) – datapackage.json
  • destination (str) – Destination of copied datapackage
  • name (optional) (str) – Name of datapackage
  • only_data (str) – Name of directory to only copy subset of datapackage (for example only the ‘data’ directory)
oemof.tabular.datapackage.processing.to_dict(value)[source]

Convert value from e.g. csv-reader to valid json / dict

oemof.tabular.datapackage.reading module

Tools to deserialize energy systems from datapackages.

WARNING

This is work in progress and still pretty volatile, so use it at your own risk. The datapackage format and conventions we use are still a bit in flux. This is also why we don’t have documentation or tests yet. Once things are stabilized a bit more, the way in which we extend the datapackage spec will be documented along with how to use the functions in this module.

oemof.tabular.datapackage.reading.deserialize_energy_system(cls, path, typemap={}, attributemap={})[source]
oemof.tabular.datapackage.reading.read_facade(facade, facades, create, typemap, data, objects, sequence_names, fks, resources)[source]

Parse the resource r as a facade.

oemof.tabular.datapackage.reading.sequences(r, timeindices=None)[source]

Parses the resource r as a sequence.

oemof.tabular.tools package

oemof.tabular’s kitchen sink module.

Contains all the general tools needed by other tools dealing with specific tabular data sources.

class oemof.tabular.tools.HSN[source]

Bases: types.SimpleNamespace

A hashable variant of types.Simplenamespace.

By making it hashable, we can use the instances as dictionary keys, which is necessary, as this is the default type for flows.

oemof.tabular.tools.raisestatement(exception, message='')[source]

A version of raise that can be used as a statement.

oemof.tabular.tools.remap(mapping, renamings, selection)[source]

Change mapping’s keys according to the selection in renamings.

The renaming found under selection in renamings is used to rename the keys found in mapping. I.e., return a copy of mapping with every key of mapping that is also found in renaming replaced with renaming[key].

If key doesn’t have a renaming, it’s returned as is. If selection doesn’t appear as a key in renamings, mapping is returned unchanged.

Example

>>> renamings = {'R1': {'zero': 'nada'}, 'R2': {'foo': 'bar'}}
>>> mapping = {'zero': 0, 'foo': 'foobar'}
>>> remap(mapping, renamings, 'R1') == {'nada': 0, 'foo': 'foobar'}
True
>>> remap(mapping, renamings, 'R2') == {'zero': 0, 'bar': 'foobar'}
True

As a special case, if selection is a class, not only selection is considered to select a renaming, but the classes in selection’s mro are considered too. The first class in selection’s mro which is also found to be a key in renamings is used to determine which renaming to use. The search starts at selection.

Parameters:
  • mapping (Mapping) – The Mapping whose keys should be renamed.
  • renamings (Mapping of Mappings <collections.abc.Mapping>)
  • selection (Hashable) – Key specifying which entry in renamings is used to determine the new keys in the copy of mapping. If selection is a class, the first entry of selection’s mro which is found in renamings is used to determine the new keys.

Submodules

oemof.tabular.tools.geometry module

The code in this module is partly based on third party code which has been licensed under GNU-GPL3. The following functions are copied and adapted from:

https://github.com/FRESNA/vresutils, Copyright 2015-2017 Frankfurt Institute for Advanced Studies

  • _shape2poly()
  • simplify_poly()
  • nuts()
oemof.tabular.tools.geometry.Shapes2Shapes(orig, dest, normed=True, equalarea=False, prep_first=True, **kwargs)[source]

Notes

Copied from: https://github.com/FRESNA/vresutils, Copyright 2015-2017 Frankfurt Institute for Advanced Studies

oemof.tabular.tools.geometry.intersects(geom, labels, geometries)[source]
oemof.tabular.tools.geometry.nuts(filepath=None, nuts=0, subset=None, tolerance=0.03, minarea=1.0)[source]

Reads shapefile with nuts regions and converts to polygons

Returns:OrderedDict – Country keys as keys of dict and shapely polygons as corresponding values

Notes

Copied from: https://github.com/FRESNA/vresutils, Copyright 2015-2017 Frankfurt Institute for Advanced Studies

oemof.tabular.tools.geometry.read_geometries(filename, directory='data/geometries')[source]

Reads geometry resources from the datapackage. Data may either be stored in geojson format or as WKT representation in CSV-files.

Parameters:
  • filename (string) – Name of the elements to be read, for example buses.geojson
  • directory (string) – Directory where the file is located. Default: data/geometries
Returns:

pd.Series
oemof.tabular.tools.geometry.reproject(geom, fr=<sphinx.ext.autodoc.importer._MockObject object>, to=<sphinx.ext.autodoc.importer._MockObject object>)[source]

Notes

Copied and adapted from: https://github.com/FRESNA/vresutils, Copyright 2015-2017 Frankfurt Institute for Advanced Studies

oemof.tabular.tools.geometry.simplify_poly(poly, tolerance)[source]

Notes

Copied from: https://github.com/FRESNA/vresutils, Copyright 2015-2017 Frankfurt Institute for Advanced Studies

oemof.tabular.tools.geometry.write_geometries(filename, geometries, directory='data/geometries')[source]

Writes geometries to filesystem.

Parameters:
  • filename (string) – Name of the geometries stored, for example buses.geojson
  • geometries (pd.Series) – Index entries become name fields in GeoJSON properties.
  • directory (string) – Directory where the file is stored. Default: data/geometries
Returns:

path (string) – Returns the path where the file has been stored.

oemof.tabular.facades module

Facade’s are classes providing a simplified view on more complex classes.

More specifically, the Facade`s in this module act as simplified, energy specific wrappers around `oemof’s and oemof.solph’s more abstract and complex classes. The idea is to be able to instantiate a Facade using keyword arguments, whose value are derived from simple, tabular data sources. Under the hood the Facade then uses these arguments to construct an oemof or oemof.solph component and sets it up to be easily used in an EnergySystem.

Note The mathematical notation is as follows:

  • Optimization variables (endogenous variables) are denoted by \(x\)
  • Optimization parameters (exogenous variables) are denoted by \(c\)
  • The set of timesteps \(T\) describes all timesteps of the optimization problem

SPDX-License-Identifier: BSD-3-Clause

class oemof.tabular.facades.BackpressureTurbine(*args, **kwargs)[source]

Bases: oemof.solph.network.transformer.Transformer, oemof.tabular.facades.Facade

Combined Heat and Power (backpressure) unit with one input and two outputs.

Parameters:
  • electricity_bus (oemof.solph.Bus) – An oemof bus instance where the chp unit is connected to with its electrical output
  • heat_bus (oemof.solph.Bus) – An oemof bus instance where the chp unit is connected to with its thermal output
  • fuel_bus (oemof.solph.Bus) – An oemof bus instance where the chp unit is connected to with its input
  • carrier_cost (numeric) – Input carrier cost of the backpressure unit, Default: 0
  • capacity (numeric) – The electrical capacity of the chp unit (e.g. in MW).
  • electric_efficiency – Electrical efficiency of the chp unit
  • thermal_efficiency – Thermal efficiency of the chp unit
  • marginal_cost (numeric) – Marginal cost for one unit of produced electrical output E.g. for a powerplant: marginal cost =fuel cost + operational cost + co2 cost (in Euro / MWh) if timestep length is one hour. Default: 0
  • expandable (boolean) – True, if capacity can be expanded within optimization. Default: False.
  • capacity_cost (numeric) – Investment costs per unit of electrical capacity (e.g. Euro / MW) . If capacity is not set, this value will be used for optimizing the chp capacity.

Backpressure turbine power plants are modelled with a constant relation between heat and electrical output (power to heat coefficient).

\[\begin{split}x^{flow, carrier}(t) = \frac{x^{flow, electricity}(t) + x^{flow, heat}(t)}\ {c^{thermal\:efficiency}(t) + c^{electrical\:efficiency}(t)} \\ \qquad \forall t \in T\end{split}\]
\[\frac{x^{flow, electricity}(t)}{x_{flow, thermal}(t)} = \frac{c^{electrical\:efficiency}(t)}{c^{thermal\:efficiency}(t)} \qquad \forall t \in T\]

Objective expression for operation includes marginal cost and/or carrier costs:

\[x^{opex} = \sum_t (x^{flow, out}(t) \cdot c^{marginal\_cost}(t) + x^{flow, carrier}(t) \cdot c^{carrier\_cost}(t))\]

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_elec_bus = solph.Bus('my_elec_bus')
>>> my_fuel_bus = solph.Bus('my_fuel_bus')
>>> my_heat_bus = solph.Bus('my_heat_bus')
>>> my_backpressure = BackpressureTurbine(
...     label='backpressure',
...     carrier='gas',
...     tech='bp',
...     fuel_bus=my_fuel_bus,
...     heat_bus=my_heat_bus,
...     electricity_bus=my_elec_bus,
...     capacity_cost=50,
...     carrier_cost=0.6,
...     electric_efficiency=0.4,
...     thermal_efficiency=0.35)
build_solph_components()[source]
capacity = None
capacity_cost = None
carrier_cost = 0
expandable = False
marginal_cost = 0
class oemof.tabular.facades.Commodity(*args, **kwargs)[source]

Bases: oemof.solph.network.source.Source, oemof.tabular.facades.Facade

Commodity element with one output for example a biomass commodity

Parameters:
  • bus (oemof.solph.Bus) – An oemof bus instance where the unit is connected to with its output
  • amount (numeric) – Total available amount to be used within the complete timehorzion of the problem
  • marginal_cost (numeric) – Marginal cost for one unit used commodity
  • output_paramerters (dict (optional)) – Parameters to set on the output edge of the component (see. oemof.solph Edge/Flow class for possible arguments)
\[\sum_{t} x^{flow}(t) \leq c^{amount}\]

For constraints set through output_parameters see oemof.solph.Flow class.

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_bus = solph.Bus('my_bus')
>>> my_commodity = Commodity(
...     label='biomass-commodity',
...     bus=my_bus,
...     carrier='biomass',
...     amount=1000,
...     marginal_cost=10,
...     output_parameters={
...         'max': [0.9, 0.5, 0.4]})
build_solph_components()[source]
marginal_cost = 0
class oemof.tabular.facades.Conversion(*args, **kwargs)[source]

Bases: oemof.solph.network.transformer.Transformer, oemof.tabular.facades.Facade

Conversion unit with one input and one output.

Parameters:

  • from_bus (oemof.solph.Bus) – An oemof bus instance where the conversion unit is connected to with its input.

  • to_bus (oemof.solph.Bus) – An oemof bus instance where the conversion unit is connected to with its output.

  • capacity (numeric) – The conversion capacity (output side) of the unit.

  • efficiency (numeric) – Efficiency of the conversion unit (0 <= efficiency <= 1). Default: 1

  • marginal_cost (numeric) – Marginal cost for one unit of produced output. Default: 0

  • carrier_cost (numeric) – Carrier cost for one unit of used input. Default: 0

  • capacity_cost (numeric) – Investment costs per unit of output capacity. If capacity is not set, this value will be used for optimizing the conversion output capacity.

  • expandable (boolean or numeric (binary)) – True, if capacity can be expanded within optimization. Default: False.

  • capacity_potential (numeric) – Maximum invest capacity in unit of output capacity.

  • capacity_minimum (numeric) – Minimum invest capacity in unit of output capacity.

  • input_parameters (dict (optional)) – Set parameters on the input edge of the conversion unit (see oemof.solph for more information on possible parameters)

  • ouput_parameters (dict (optional)) –

    Set parameters on the output edge of the conversion unit

    (see oemof.solph for more information on possible parameters)
\[x^{flow, from}(t) \cdot c^{efficiency}(t) = x^{flow, to}(t) \qquad \forall t \in T\]

Objective expression for operation includes marginal cost and/or carrier costs:

\[x^{opex} = \sum_t (x^{flow, out}(t) \cdot c^{marginal\_cost}(t) + x^{flow, carrier}(t) \cdot c^{carrier\_cost}(t))\]

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_biomass_bus = solph.Bus('my_biomass_bus')
>>> my_heat_bus = solph.Bus('my_heat_bus')
>>> my_conversion = Conversion(
...     label='biomass_plant',
...     carrier='biomass',
...     tech='st',
...     from_bus=my_biomass_bus,
...     to_bus=my_heat_bus,
...     capacity=100,
...     efficiency=0.4)
build_solph_components()[source]
capacity = None
capacity_cost = None
capacity_minimum = None
capacity_potential = inf
carrier_cost = 0
efficiency = 1
expandable = False
marginal_cost = 0
class oemof.tabular.facades.Dispatchable(*args, **kwargs)[source]

Bases: oemof.solph.network.source.Source, oemof.tabular.facades.Facade

Dispatchable element with one output for example a gas-turbine

Parameters:
  • bus (oemof.solph.Bus) – An oemof bus instance where the unit is connected to with its output
  • capacity (numeric) – The installed power of the generator (e.g. in MW). If not set the capacity will be optimized (s. also capacity_cost argument)
  • profile (array-like (optional)) – Profile of the output such that profile[t] * installed capacity yields the upper bound for timestep t
  • marginal_cost (numeric) – Marginal cost for one unit of produced output, i.e. for a powerplant: mc = fuel_cost + co2_cost + … (in Euro / MWh) if timestep length is one hour. Default: 0
  • capacity_cost (numeric (optional)) – Investment costs per unit of capacity (e.g. Euro / MW) . If capacity is not set, this value will be used for optimizing the generators capacity.
  • expandable (boolean) – True, if capacity can be expanded within optimization. Default: False.
  • output_paramerters (dict (optional)) – Parameters to set on the output edge of the component (see. oemof.solph Edge/Flow class for possible arguments)
  • capacity_potential (numeric) – Max install capacity if capacity is to be expanded
  • capacity_minimum (numeric) – Minimum install capacity if capacity is to be expanded

The mathematical representations for these components are dependent on the user defined attributes. If the capacity is fixed before (dispatch mode) the following equation holds:

\[x^{flow}(t) \leq c^{capacity} \cdot c^{profile}(t) \ \qquad \forall t \in T\]

Where \(x^{flow}\) denotes the production (endogenous variable) of the dispatchable object to the bus.

If expandable is set to True (investment mode), the equation changes slightly:

\[x^{flow}(t) \leq (x^{capacity} + c^{capacity}) \cdot c^{profile}(t) \qquad \forall t \in T\]

Where the bounded endogenous variable of the volatile component is added:

\[x^{capacity} \leq c^{capacity\_potential}\]

Objective expression for operation:

\[x^{opex} = \sum_t x^{flow}(t) \cdot c^{marginal\_cost}(t)\]

For constraints set through output_parameters see oemof.solph.Flow class.

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_bus = solph.Bus('my_bus')
>>> my_dispatchable = Dispatchable(
...     label='ccgt',
...     bus=my_bus,
...     carrier='gas',
...     tech='ccgt',
...     capacity=1000,
...     marginal_cost=10,
...     output_parameters={
...         'min': 0.2})
build_solph_components()[source]
capacity = None
capacity_cost = None
capacity_minimum = None
capacity_potential = inf
expandable = False
marginal_cost = 0
profile = 1
class oemof.tabular.facades.Excess(*args, **kwargs)[source]

Bases: oemof.solph.network.sink.Sink, oemof.tabular.facades.Facade

build_solph_components()[source]
capacity = None
capacity_cost = None
capacity_minimum = None
capacity_potential = inf
expandable = False
marginal_cost = 0
class oemof.tabular.facades.ExtractionTurbine(*args, **kwargs)[source]

Bases: oemof.solph.components.extraction_turbine_chp.ExtractionTurbineCHP, oemof.tabular.facades.Facade

Combined Heat and Power (extraction) unit with one input and two outputs.

Parameters:
  • electricity_bus (oemof.solph.Bus) – An oemof bus instance where the chp unit is connected to with its electrical output
  • heat_bus (oemof.solph.Bus) – An oemof bus instance where the chp unit is connected to with its thermal output
  • fuel_bus (oemof.solph.Bus) – An oemof bus instance where the chp unit is connected to with its input
  • carrier_cost (numeric) – Cost per unit of used input carrier
  • capacity (numeric) – The electrical capacity of the chp unit (e.g. in MW) in full extraction mode.
  • electric_efficiency – Electrical efficiency of the chp unit in full backpressure mode
  • thermal_efficiency – Thermal efficiency of the chp unit in full backpressure mode
  • condensing_efficiency – Electrical efficiency if turbine operates in full extraction mode
  • marginal_cost (numeric) – Marginal cost for one unit of produced electrical output E.g. for a powerplant: marginal cost =fuel cost + operational cost + co2 cost (in Euro / MWh) if timestep length is one hour.
  • capacity_cost (numeric) – Investment costs per unit of electrical capacity (e.g. Euro / MW) . If capacity is not set, this value will be used for optimizing the chp capacity.
  • expandable (boolean) – True, if capacity can be expanded within optimization. Default: False.

The mathematical description is derived from the oemof base class ExtractionTurbineCHP :

\[x^{flow, carrier}(t) = \frac{x^{flow, electricity}(t) + x^{flow, heat}(t) \ \cdot c^{beta}(t)}{c^{condensing\_efficiency}(t)} \qquad \forall t \in T\]
\[x^{flow, electricity}(t) \geq x^{flow, thermal}(t) \cdot \frac{c^{electrical\_efficiency}(t)}{c^{thermal\_efficiency}(t)} \qquad \forall t \in T\]

where \(c^{beta}\) is defined as:

\[c^{beta}(t) = \frac{c^{condensing\_efficiency}(t) - c^{electrical\_efficiency(t)}}{c^{thermal\_efficiency}(t)} \qquad \forall t \in T\]

Objective expression for operation includes marginal cost and/or carrier costs:

\[x^{opex} = \sum_t (x^{flow, out}(t) \cdot c^{marginal\_cost}(t) + x^{flow, carrier}(t) \cdot c^{carrier\_cost}(t))\]

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_elec_bus = solph.Bus('my_elec_bus')
>>> my_fuel_bus = solph.Bus('my_fuel_bus')
>>> my_heat_bus = solph.Bus('my_heat_bus')
>>> my_extraction = ExtractionTurbine(
...     label='extraction',
...     carrier='gas',
...     tech='ext',
...     electricity_bus=my_elec_bus,
...     heat_bus=my_heat_bus,
...     fuel_bus=my_fuel_bus,
...     capacity=1000,
...     condensing_efficiency=[0.5, 0.51, 0.55],
...     electric_efficiency=0.4,
...     thermal_efficiency=0.35)
build_solph_components()[source]
capacity = None
capacity_cost = None
carrier_cost = 0
expandable = False
marginal_cost = 0
class oemof.tabular.facades.Facade(*args, **kwargs)[source]

Bases: oemof.network.network.Node

Parent class for oemof.tabular facades.

update()[source]
class oemof.tabular.facades.Generator(*args, **kwargs)[source]

Bases: oemof.tabular.facades.Dispatchable

class oemof.tabular.facades.HeatPump(*args, **kwargs)[source]

Bases: oemof.solph.network.transformer.Transformer, oemof.tabular.facades.Facade

HeatPump unit with two inputs and one output.

Parameters:

  • low_temperature_bus (oemof.solph.Bus) – An oemof bus instance where unit is connected to with its low temperature input.

  • high_temperature_bus (oemof.solph.Bus) – An oemof bus instance where the unit is connected to with its high temperature input.

  • capacity (numeric) – The thermal capacity (high temperature output side) of the unit.

  • cop (numeric) – Coefficienct of performance

  • carrier_cost (numeric) – Carrier cost for one unit of used input. Default: 0

  • capacity_cost (numeric) – Investment costs per unit of output capacity. If capacity is not set, this value will be used for optimizing the conversion output capacity.

  • expandable (boolean or numeric (binary)) – True, if capacity can be expanded within optimization. Default: False.

  • capacity_potential (numeric) – Maximum invest capacity in unit of output capacity. Default: +inf.

  • low_temperature_parameters (dict (optional)) – Set parameters on the input edge of the heat pump unit (see oemof.solph for more information on possible parameters)

  • high_temperature_parameters (dict (optional)) – Set parameters on the output edge of the heat pump unit (see oemof.solph for more information on possible parameters)

  • input_parameters (dict (optional)) –

    Set parameters on the input edge of the conversion unit

    (see oemof.solph for more information on possible parameters)
\[x_{electricity\_bus, hp}^{flow} = \frac{1}{c^{COP}} \cdot x_{hp, high\_temperature\_bus}^{flow}\]
\[x_{low\_temperature\_source, low\_temperature\_bus}^{flow} = x_{hp, high\_temperature\_bus}^{flow} \frac{c^{COP} -1}{c^{COP}}\]

Objective expression for operation includes marginal cost and/or carrier costs:

\[x^{opex} = \sum_t (x^{flow, out}(t) \cdot c^{marginal\_cost}(t) + x^{flow, carrier}(t) \cdot c^{carrier\_cost}(t))\]

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> electricity_bus = solph.Bus("elec-bus")
>>> heat_bus= solph.Bus('heat_bus')
>>> heat_bus_low = solph.Bus('heat_bus_low')
>>> fc.HeatPump(
...     label="hp-storage",
...     carrier="electricity",
...     tech="hp",
...     cop=3,
...     carrier_cost=15,
...     electricity_bus=elec_bus,
...     high_temperature_bus=heat_bus,
...     low_temperature_bus=heat_bus_low)
build_solph_components()[source]
capacity = None
capacity_cost = None
capacity_potential = inf
carrier_cost = 0
expandable = False
marginal_cost = 0

Bases: oemof.solph.custom.link.Link, oemof.tabular.facades.Facade

Bidirectional link for two buses, e.g. to model transshipment.

Parameters:
  • from_bus (oemof.solph.Bus) – An oemof bus instance where the link unit is connected to with its input.
  • to_bus (oemof.solph.Bus) – An oemof bus instance where the link unit is connected to with its output.
  • from_to_capacity (numeric) – The maximal capacity (output side to bus) of the unit. If not set, attr capacity_cost needs to be set.
  • to_from_capacity (numeric) – The maximal capacity (output side from bus) of the unit. If not set, attr capacity_cost needs to be set.
  • loss – Relative loss through the link (default: 0)
  • capacity_cost (numeric) – Investment costs per unit of output capacity. If capacity is not set, this value will be used for optimizing the chp capacity.
  • marginal_cost (numeric) – Cost per unit Transport in each timestep. Default: 0
  • expandable (boolean) – True, if capacity can be expanded within optimization. Default: False.

Note

Assigning a small value like 0.00001 to marginal_cost may force unique solution of optimization problem.

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_elec_bus_1 = solph.Bus('my_elec_bus_1')
>>> my_elec_bus_2 = solph.Bus('my_elec_bus_2')
>>> my_loadink = Link(
...     label='link',
...     carrier='electricity',
...     from_bus=my_elec_bus_1,
...     to_bus=my_elec_bus_2,
...     from_to_capacity=100,
...     to_from_capacity=80,
...     loss=0.04)
build_solph_components()[source]
capacity_cost = None
expandable = False
from_to_capacity = None
limit_direction = False
loss = 0
marginal_cost = 0
to_from_capacity = None
class oemof.tabular.facades.Load(*args, **kwargs)[source]

Bases: oemof.solph.network.sink.Sink, oemof.tabular.facades.Facade

Load object with one input

Parameters:
  • bus (oemof.solph.Bus) – An oemof bus instance where the demand is connected to.
  • amount (numeric) – The total amount for the timehorzion (e.g. in MWh)
  • profile (array-like) – Load profile with normed values such that profile[t] * amount yields the load in timestep t (e.g. in MWh)
  • marginal_utility (numeric) – Marginal utility in for example Euro / MWh
  • input_parameters (dict (optional))
\[x^{flow}(t) = c^{amount}(t) \cdot x^{flow}(t) \qquad \forall t \in T\]

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_bus = solph.Bus('my_bus')
>>> my_load = Load(
...     label='load',
...     carrier='electricity',
...     bus=my_bus,
...     amount=100,
...     profile=[0.3, 0.2, 0.5])
build_solph_components()[source]
marginal_utility = 0
class oemof.tabular.facades.Reservoir(*args, **kwargs)[source]

Bases: oemof.solph.components.generic_storage.GenericStorage, oemof.tabular.facades.Facade

A Reservoir storage unit, that is initially half full.

Note that the investment option is not available for this facade at the current development state.

Parameters:
  • bus (oemof.solph.Bus) – An oemof bus instance where the storage unit is connected to.
  • storage_capacity (numeric) – The total storage capacity of the storage (e.g. in MWh)
  • capacity (numeric) – Installed production capacity of the turbine installed at the reservoir
  • efficiency (numeric) – Efficiency of the turbine converting inflow to electricity production, default: 1
  • profile (array-like) – Absolute inflow profile of inflow into the storage
  • output_parameters (dict) – Dictionary to specifiy parameters on the output edge. You can use all keys that are available for the oemof.solph.network.Flow class.

The reservoir is modelled as a storage with a constant inflow:

\[x^{level}(t) = x^{level}(t-1) \cdot (1 - c^{loss\_rate}(t)) + x^{profile}(t) - \frac{x^{flow, out}(t)}{c^{efficiency}(t)} \qquad \forall t \in T\]
\[x^{level}(0) = 0.5 \cdot c^{capacity}\]

The inflow is bounded by the exogenous inflow profile. Thus if the inflow exceeds the maximum capacity of the storage, spillage is possible by setting \(x^{profile}(t)\) to lower values.

\[0 \leq x^{profile}(t) \leq c^{profile}(t) \qquad \forall t \in T\]

The spillage of the reservoir is therefore defined by: \(c^{profile}(t) - x^{profile}(t)\).

Note

As the Reservoir is a sub-class of oemof.solph.GenericStorage you also pass all arguments of this class.

Examples

Basic usage examples of the GenericStorage with a random selection of attributes. See the Flow class for all Flow attributes.

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_bus = solph.Bus('my_bus')
>>> my_reservoir = Reservoir(
...     label='my_reservoir',
...     bus=my_bus,
...     carrier='water',
...     tech='reservoir',
...     storage_capacity=1000,
...     capacity=50,
...     profile=[1, 2, 6],
...     loss_rate=0.01,
...     initial_storage_level=0,
...     max_storage_level = 0.9,
...     efficiency=0.93)
build_solph_components()[source]
capacity = None
expandable = False
storage_capacity = None
class oemof.tabular.facades.Shortage(*args, **kwargs)[source]

Bases: oemof.tabular.facades.Dispatchable

class oemof.tabular.facades.Storage(*args, **kwargs)[source]

Bases: oemof.solph.components.generic_storage.GenericStorage, oemof.tabular.facades.Facade

Storage unit

Parameters:
  • bus (oemof.solph.Bus) – An oemof bus instance where the storage unit is connected to.
  • storage_capacity (numeric) – The total capacity of the storage (e.g. in MWh)
  • capacity (numeric) – Maximum production capacity (e.g. in MW)
  • efficiency (numeric) – Efficiency of charging and discharging process: Default: 1
  • storage_capacity_cost (numeric) – Investment costs for the storage unit e.g in €/MWh-capacity
  • capacity_cost (numeric) – Investment costs for the storage unit e.g in €/MW-capacity
  • expandable (boolean) – True, if capacity can be expanded within optimization. Default: False.
  • storage_capacity_potential (numeric) – Potential of the investment for storage capacity in MWh. Default: +inf.
  • capacity_potential (numeric) – Potential of the investment for capacity in MW. Default: +inf.
  • input_parameters (dict (optional)) – Set parameters on the input edge of the storage (see oemof.solph for more information on possible parameters)
  • ouput_parameters (dict (optional)) – Set parameters on the output edge of the storage (see oemof.solph for more information on possible parameters)

Intertemporal energy balance of the storage:

\[\begin{split}x^{level}(t) = x^{level}(t-1) \cdot (1 - c^{loss\_rate}) + \sqrt{c^{efficiency}(t)} x^{flow, in}(t) - \frac{x^{flow, out}(t)}{\sqrt{c^{efficiency}(t)}}\\ \qquad \forall t \in T\end{split}\]
\[x^{level}(0) = 0.5 \cdot c^{capacity}\]

The expression added to the cost minimizing objective funtion for the operation is given as:

\[x^{opex} = \sum_t (x^{flow, out}(t) \cdot c^{marginal\_cost}(t))\]

Examples

>>> import pandas as pd
>>> from oemof import solph
>>> from oemof.tabular import facades as fc
>>> my_bus = solph.Bus('my_bus')
>>> es = solph.EnergySystem(
...    timeindex=pd.date_range('2019', periods=3, freq='H'))
>>> es.add(my_bus)
>>> es.add(
...    fc.Storage(
...        label="storage",
...        bus=my_bus,
...        carrier="lithium",
...        tech="battery",
...        storage_capacity_cost=10,
...        invest_relation_output_capacity=1/6, # oemof.solph
...        marginal_cost=5,
...        balanced=True, # oemof.solph argument
...        initial_storage_level=1, # oemof.solph argument
...        max_storage_level=[0.9, 0.95, 0.8])) # oemof.solph argument
build_solph_components()[source]
capacity = 0
capacity_cost = 0
capacity_potential = inf
efficiency = 1
expandable = False
marginal_cost = 0
storage_capacity = 0
storage_capacity_cost = None
storage_capacity_potential = inf
class oemof.tabular.facades.Volatile(*args, **kwargs)[source]

Bases: oemof.solph.network.source.Source, oemof.tabular.facades.Facade

Volatile element with one output. This class can be used to model PV oder Wind power plants.

Parameters:
  • bus (oemof.solph.Bus) – An oemof bus instance where the generator is connected to
  • capacity (numeric) – The installed power of the unit (e.g. in MW).
  • profile (array-like) – Profile of the output such that profile[t] * capacity yields output for timestep t
  • marginal_cost (numeric) – Marginal cost for one unit of produced output, i.e. for a powerplant: mc = fuel_cost + co2_cost + … (in Euro / MWh) if timestep length is one hour.
  • capacity_cost (numeric (optional)) – Investment costs per unit of capacity (e.g. Euro / MW) . If capacity is not set, this value will be used for optimizing the generators capacity.
  • output_paramerters (dict (optional)) – Parameters to set on the output edge of the component (see. oemof.solph Edge/Flow class for possible arguments)
  • capacity_potential (numeric) – Max install capacity if investment
  • capacity_minimum (numeric) – Minimum install capacity if investment
  • expandable (boolean) – True, if capacity can be expanded within optimization. Default: False.

The mathematical representations for this components are dependent on the user defined attributes. If the capacity is fixed before (dispatch mode) the following equation holds:

\[x^{flow}(t) = c^{capacity} \cdot c^{profile}(t) \qquad \forall t \in T\]

Where \(x_{volatile}^{flow}\) denotes the production (endogenous variable) of the volatile object to the bus.

If expandable is set to True (investment mode), the equation changes slightly:

\[x^{flow}(t) = (x^{capacity} + c^{capacity}) \ \cdot c^{profile}(t) \qquad \forall t \in T\]

Where the bounded endogenous variable of the volatile component is added:

\[x_{volatile}^{capacity} \leq c_{volatile}^{capacity\_potential}\]

Objective expression for operation:

\[x^{opex} = \sum_t (x^{flow}(t) \cdot c^{marginal\_cost}(t))\]

Examples

>>> from oemof import solph
>>> from oemof.tabular import facades
>>> my_bus = solph.Bus('my_bus')
>>> my_volatile = Volatile(
...     label='wind',
...     bus=my_bus,
...     carrier='wind',
...     tech='onshore',
...     capacity_cost=150,
...     profile=[0.25, 0.1, 0.3])
build_solph_components()[source]
capacity = None
capacity_cost = None
capacity_minimum = None
capacity_potential = inf
expandable = False
marginal_cost = 0
oemof.tabular.facades.add_subnodes(n, **kwargs)[source]
oemof.tabular.facades.dataclass_facade(cls)[source]

Decorates a facade class by first as a dataclass, taking care of args and kwargs in the __init__

Parameters:cls (facade class)
Returns:cls (facade class)
oemof.tabular.facades.kwargs_to_parent(cls)[source]

Decorates the __init__ of a given class by first passing args and kwargs to the __init__ of the parent class.

Parameters:cls (Class with an __init__ to decorate)
Returns:cls (Class with decorated __init__)