oemof package


oemof.energy_system module

Basic EnergySystem class

This file is part of project oemof (github.com/oemof/oemof). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location oemof/oemof/energy_system.py

SPDX-License-Identifier: GPL-3.0-or-later

class oemof.energy_system.EnergySystem(**kwargs)[source]

Bases: object

Defining an energy supply system to use oemof’s solver libraries.


The list of regions is not necessary to use the energy system with solph.

  • entities (list of Entity, optional) – A list containing the already existing Entities that should be part of the energy system. Stored in the entities attribute. Defaults to [] if not supplied.
  • timeindex (pandas.datetimeindex) – Define the time range and increment for the energy system.
  • groupings (list) – The elements of this list are used to construct Groupings or they are used directly if they are instances of Grouping. These groupings are then used to aggregate the entities added to this energy system into groups. By default, there’ll always be one group for each uid containing exactly the entity with the given uid. See the examples for more information.

list of Entity – A list containing the Entities that comprise the energy system. If this EnergySystem is set as the registry attribute, which is done automatically on EnergySystem construction, newly created Entities are automatically added to this list on construction.




dictionary – A dictionary holding the results produced by the energy system. Is None while no results are produced. Currently only set after a call to optimize() after which it holds the return value of om.results(). See the documentation of that method for a detailed description of the structure of the results dictionary.


pandas.index, optional – Define the time range and increment for the energy system. This is an optional attribute but might be import for other functions/methods that use the EnergySystem class as an input parameter.


Regardles of additional groupings, entities will always be grouped by their uid:

>>> from oemof.network import Entity
>>> from oemof.network import Bus, Sink
>>> es = EnergySystem()
>>> bus = Bus(label='electricity')
>>> es.add(bus)
>>> bus is es.groups['electricity']

For simple user defined groupings, you can just supply a function that computes a key from an entity and the resulting groups will be sets of entities stored under the returned keys, like in this example, where entities are grouped by their type:

>>> es = EnergySystem(groupings=[type])
>>> buses = set(Bus(label="Bus {}".format(i)) for i in range(9))
>>> es.add(*buses)
>>> components = set(Sink(label="Component {}".format(i))
...                   for i in range(9))
>>> es.add(*components)
>>> buses == es.groups[Bus]
>>> components == es.groups[Sink]

Add nodes to this energy system.

dump(dpath=None, filename=None)[source]

Dump an EnergySystem instance.

classmethod from_datapackage(*args, **kwargs)[source]
restore(dpath=None, filename=None)[source]

Restore an EnergySystem instance.

oemof.graph module

Modules for creating and analysing energy system graphs.

This file is part of project oemof (github.com/oemof/oemof). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location oemof/oemof/graph.py

SPDX-License-Identifier: GPL-3.0-or-later

oemof.graph.create_nx_graph(energy_system=None, optimization_model=None, remove_nodes=None, filename=None, remove_nodes_with_substrings=None, remove_edges=None)[source]

Create a networkx.DiGraph for the passed energy system and plot it. See http://networkx.readthedocs.io/en/latest/ for more information.

  • energy_system (oemof.solph.network.EnergySystem) –
  • filename (str) – Absolute filename (with path) to write your graph in the graphml format. If no filename is given no file will be written.
  • remove_nodes (list of strings) – Nodes to be removed e.g. [‘node1’, node2’)]
  • remove_nodes_with_substrings (list of strings) – Nodes that contain substrings to be removed e.g. [‘elec’, ‘heat’)]
  • remove_edges (list of string tuples) – Edges to be removed e.g. [(‘resource_gas’, ‘gas_balance’)]


>>> import os
>>> import pandas as pd
>>> from oemof.solph import (Bus, Sink, Transformer, Flow, EnergySystem)
>>> import oemof.graph as grph
>>> datetimeindex = pd.date_range('1/1/2017', periods=3, freq='H')
>>> es = EnergySystem(timeindex=datetimeindex)
>>> b_gas = Bus(label='b_gas', balanced=False)
>>> bel1 = Bus(label='bel1')
>>> bel2 = Bus(label='bel2')
>>> demand_el = Sink(label='demand_el',
...                  inputs = {bel1: Flow(nominal_value=85,
...                            actual_value=[0.5, 0.25, 0.75],
...                            fixed=True)})
>>> pp_gas = Transformer(label='pp_gas',
...                            inputs={b_gas: Flow()},
...                            outputs={bel1: Flow(nominal_value=41,
...                                                variable_costs=40)},
...                            conversion_factors={bel1: 0.5})
>>> line_to2 = Transformer(label='line_to2',
...                        inputs={bel1: Flow()}, outputs={bel2: Flow()})
>>> line_from2 = Transformer(label='line_from2',
...                          inputs={bel2: Flow()}, outputs={bel1: Flow()})
>>> es.add(b_gas, bel1, demand_el, pp_gas, bel2, line_to2, line_from2)
>>> my_graph = grph.create_nx_graph(es)
>>> # export graph as .graphml for programs like Yed where it can be
>>> # sorted and customized. this is especially helpful for large graphs
>>> # grph.create_nx_graph(es, filename="my_graph.graphml")
>>> [my_graph.has_node(n)
...  for n in ['b_gas', 'bel1', 'pp_gas', 'demand_el', 'tester']]
[True, True, True, True, False]
>>> list(nx.attracting_components(my_graph))
>>> sorted(list(nx.strongly_connected_components(my_graph))[1])
['bel1', 'bel2', 'line_from2', 'line_to2']
>>> new_graph = grph.create_nx_graph(energy_system=es,
...                                  remove_nodes_with_substrings=['b_'],
...                                  remove_nodes=['pp_gas'],
...                                  remove_edges=[('bel2', 'line_from2')],
...                                  filename='test_graph')
>>> [new_graph.has_node(n)
...  for n in ['b_gas', 'bel1', 'pp_gas', 'demand_el', 'tester']]
[False, True, False, True, False]
>>> my_graph.has_edge('pp_gas', 'bel1')
>>> new_graph.has_edge('bel2', 'line_from2')
>>> os.remove('test_graph.graphml')


Needs graphviz and networkx (>= v.1.11) to work properly. Tested on Ubuntu 16.04 x64 and solydxk (debian 9).

oemof.groupings module

All you need to create groups of stuff in your energy system.

This file is part of project oemof (github.com/oemof/oemof). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location oemof/oemof/groupings.py

SPDX-License-Identifier: GPL-3.0-or-later

oemof.groupings.DEFAULT = <oemof.groupings.Grouping object>

The default Grouping.

This one is always present in an energy system. It stores every entity under its uid and raises an error if another entity with the same uid get’s added to the energy system.

class oemof.groupings.Flows(key=None, constant_key=None, filter=None, **kwargs)[source]

Bases: oemof.groupings.Nodes

Specialises Grouping to group the flows connected to nodes into sets. Note that this specifically means that the key, and value functions act on a set of flows.


Returns a set containing only flows, so groups are sets of flows.

class oemof.groupings.FlowsWithNodes(key=None, constant_key=None, filter=None, **kwargs)[source]

Bases: oemof.groupings.Nodes

Specialises Grouping to act on the flows connected to nodes and create sets of (source, target, flow) tuples. Note that this specifically means that the key, and value functions act on sets like these.


Returns a set containing only tuples, so groups are sets of tuples.

class oemof.groupings.Grouping(key=None, constant_key=None, filter=None, **kwargs)[source]

Bases: object

Used to aggregate entities in an energy system into groups.

The way Groupings work is that each Grouping g of an energy system is called whenever an entity is added to the energy system (and for each entity already present, if the energy system is created with existing enties). The call g(e, groups), where e is an entity and groups is a dictionary mapping group keys to groups, then uses the three functions key, value and merge in the following way:

  • key(e) is called to obtain a key k under which the group should be stored,
  • value(e) is called to obtain a value v (the actual group) to store under k,
  • if you supplied a filter() argument, v is filtered using that function,
  • otherwise, if there is not yet anything stored under groups[k], groups[k] is set to v. Otherwise merge is used to figure out how to merge v into the old value of groups[k], i.e. groups[k] is set to merge(v, groups[k]).

Instead of trying to use this class directly, have a look at its subclasses, like Nodes, which should cater for most use cases.


When overriding methods using any of the constructor parameters, you don’t have access to self in the corresponding function. If you need access to self, subclass Grouping and override the methods in the subclass.

A Grouping may be called more than once on the same object e, so one should make sure that user defined Grouping g is idempotent, i.e. g(e, g(e, d)) == g(e, d).

  • key (callable or hashable) – Specifies (if not callable) or extracts (if callable) a key for each entity of the energy system.
  • constant_key (hashable (optional)) – Specifies a constant key. Keys specified using this parameter are not called but taken as is.
  • value (callable, optional) – Overrides the default behaviour of value.
  • filter (callable, optional) – If supplied, whatever is returned by value() is filtered through this. Mostly useful in conjunction with static (i.e. non-callable) keys. See filter() for more details.
  • merge (callable, optional) – Overrides the default behaviour of merge.

Filter the group returned by value() before storing it.

Should return a boolean value. If the group returned by value() is iterable, this function is used (via Python’s builtin filter) to select the values which should be retained in group. If group is not iterable, it is simply called on group itself and the return value decides whether group is stored (True) or not (False).


Obtain a key under which to store the group.

You have to supply this method yourself using the key parameter when creating Grouping instances.

Called for every entity e of the energy system. Expected to return the key (i.e. a valid hashable) under which the group value(e) will be stored. If it should be added to more than one group, return a list (or any other non-hashable, iterable) containing the group keys.

Return None if you don’t want to store e in a group.

merge(new, old)[source]

Merge a known old group with a new one.

This method is called if there is already a value stored under group[key(e)]. In that case, merge(value(e), group[key(e)]) is called and should return the new group to store under key(e).

The default behaviour is to raise an error if new and old are not identical.


Generate the group obtained from e.

This methd returns the actual group obtained from e. Like key, it is called for every e in the energy system. If there is no group stored under key(e), groups[key(e)] is set to value(e). Otherwise merge(value(e), groups[key(e)]) is called.

The default returns the entity itself.

class oemof.groupings.Nodes(key=None, constant_key=None, filter=None, **kwargs)[source]

Bases: oemof.groupings.Grouping

Specialises Grouping to group nodes into sets.

merge(new, old)[source]

Updates old to be the union of old and new.


Returns a set containing only e, so groups are sets of node.

oemof.network module

This package (along with its subpackages) contains the classes used to model energy systems. An energy system is modelled as a graph/network of entities with very specific constraints on which types of entities are allowed to be connected.

This file is part of project oemof (github.com/oemof/oemof). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location oemof/oemof/network.py

SPDX-License-Identifier: GPL-3.0-or-later

class oemof.network.Bus(*args, **kwargs)[source]

Bases: oemof.network.Node

class oemof.network.Component(*args, **kwargs)[source]

Bases: oemof.network.Node

class oemof.network.Entity(**kwargs)[source]

Bases: object

The most abstract type of vertex in an energy system graph. Since each entity in an energy system has to be uniquely identifiable and connected (either via input or via output) to at least one other entity, these properties are collected here so that they are shared with descendant classes.

  • uid (string or tuple) – Unique component identifier of the entity.
  • inputs (list) – List of Entities acting as input to this Entity.
  • outputs (list) – List of Entities acting as output from this Entity.
  • geo_data (shapely.geometry object) – Geo-spatial data with informations for location/region-shape. The geometry can be a polygon/multi-polygon for regions, a line fore transport objects or a point for objects such as transformer sources.

EnergySystem – The central registry keeping track of all Node's created. If this is None, Node instances are not kept track of. Assign an EnergySystem to this attribute to have it become the a node registry, i.e. all nodes created are added to its nodes property on construction.


Add regions to self.regions

optimization_options = {}
registry = None
class oemof.network.Inputs(flows, target)[source]

Bases: collections.abc.MutableMapping

A special helper to map n1.inputs[n2] to n2.outputs[n1].

class oemof.network.Node(*args, **kwargs)[source]

Bases: object

Represents a Node in an energy system graph.

Abstract superclass of the two general types of nodes of an energy system graph, collecting attributes and operations common to all types of nodes. Users should neither instantiate nor subclass this, but use Component, Bus or one of their subclasses instead.

  • label (hashable, optional) – Used as the string representation of this node. If this parameter is not an instance of str it will be converted to a string and the result will be used as this node’s label, which should be unique with respect to the other nodes in the energy system graph this node belongs to. If this parameter is not supplied, the string representation of this node will instead be generated based on this nodes class and id.
  • inputs (list or dict, optional) – Either a list of this nodes’ input nodes or a dictionary mapping input nodes to corresponding inflows (i.e. input values).
  • outputs (list or dict, optional) – Either a list of this nodes’ output nodes or a dictionary mapping output nodes to corresponding outflows (i.e. output values).
  • flow (function, optional) – A function taking this node and a target node as a parameter (i.e. something of the form def f(self, target)), returning the flow originating from this node into target.

str or iterable of str – See the Python documentation on __slots__ for more information.


dict – Dictionary mapping input Nodes n to flows from n into self.


object – If this node was given a label on construction, this attribute holds the actual object passed as a parameter. Otherwise node.label is a synonym for str(node).


dict – Dictionary mapping output Nodes n to flows from self into n.

registry = None
class oemof.network.Outputs(flows, source)[source]

Bases: collections.abc.MutableMapping

Helper that intercepts modifications to update Inputs symmetrically.

class oemof.network.Sink(*args, **kwargs)[source]

Bases: oemof.network.Component

class oemof.network.Source(*args, **kwargs)[source]

Bases: oemof.network.Component

class oemof.network.Transformer(*args, **kwargs)[source]

Bases: oemof.network.Component


Override registry during execution of a block and restore it afterwards.


Backup registry before and restore it after execution of function.

Module contents