uesgraphs.UESGraph

class uesgraphs.UESGraph

A networkx Graph enhanced for use to describe urban energy systems.

name

Name of the graph

Type:

str

# TODO

Type:

delete input ids

input_ids

When input is read from json files with ids in their meta data, these ids are stored in this dict

Type:

dict

nodelist_street

List of node ids for all street nodes

Type:

list

nodelist_building

List of node ids for all building nodes

Type:

list

nodelists_heating

Dictionary contains nodelists for all heating networks. Keys are names of the networks in str format, values are lists of all node ids that belong to the network

Type:

dict

nodelists_cooling

Dictionary contains nodelists for all cooling networks. Keys are names of the networks in str format, values are lists of all node ids that belong to the network

Type:

dict

nodelists_electricity

Dictionary contains nodelists for all electricity networks. Keys are names of the networks in str format, values are lists of all node ids that belong to the network

Type:

dict

nodelists_gas

Dictionary contains nodelists for all gas networks. Keys are names of the networks in str format, values are lists of all node ids that belong to the network

Type:

dict

nodelists_others

Dictionary contains nodelists for all other networks. Keys are names of the networks in str format, values are lists of all node ids that belong to the network

Type:

dict

network_types

A list of all supported network types with their names in str format

Type:

list

nodes_by_name

A dictionary with building names for keys and node numbers for values. Used to retrieve node numbers for a given building name.

Type:

dict

positions

In general, positions in uesgraphs are defined by shapely.geometry.point objects. This attribute converts the positions into a dict of numpy arrays only for use in uesgraphs.visuals, as the networkx drawing functions need this format.

Type:

dict

min_position

Position with smallest x and y values in the graph

Type:

shapely.geometry.point object

max_position

Position with largest x and y values in the graph

Type:

shapely.geometry.point object

next_node_number

Node number for the next node to be added

Type:

int

simplification_level

Higher values indicate more simplification of the graph 0: no simplification 1: pipes connected in series are simplified to 1 aggregate pipe

Type:

int

pipeIDs

List of pipeIDs used in the graph

Type:

list

__init__()

Constructor for UESGraph class.

Methods

__init__()	Constructor for UESGraph class.
add_building([name, position, ...])	Add a building node to the UESGraph.
add_edge(u_of_edge, v_of_edge, **attr)	Add an edge between u and v.
add_edges_from(ebunch_to_add, **attr)	Add all the edges in ebunch_to_add.
add_network(network_type, network_id)	Add a new network of specified type.
add_network_node(network_type[, network_id, ...])	Add a network node to the UESGraph.
add_node(node_for_adding, **attr)	Add a single node node_for_adding and update node attributes.
add_nodes_from(nodes_for_adding, **attr)	Add multiple nodes.
add_street_node(position[, resolution, ...])	Add a street node to the UESGraph.
add_weighted_edges_from(ebunch_to_add[, weight])	Add weighted edges in ebunch_to_add with specified weight attr
adjacency()	Returns an iterator over (node, adjacency dict) tuples for all nodes.
calc_angle(a, b[, output])	Return the angle of a line from point a to b in rad or degrees.
calc_network_length(network_type)	Calculate the length of all edges for given network_type.
calc_total_building_ground_area()	Return the sum of all available building ground areas in m**2.
clear()	Remove all nodes and edges from the graph.
clear_edges()	Remove all edges from the graph without altering nodes.
copy([as_view])	Returns a copy of the graph.
create_subgraphs(network_type[, ...])	Return a list of subgraphs for each network.
edge_subgraph(edges)	Returns the subgraph induced by the specified edges.
from_geojson(network_path, buildings_path, ...)	Import district heating network from GeoJSON files.
from_json(path, network_type[, check_overlap])	Import network from json input.
from_osm(osm_file[, name, check_boundary, ...])	Import buildings and streets from OpenStreetMap data in osm_file.
get_building_node(name)	Return the node number for a given building name.
get_edge_data(u, v[, default])	Returns the attribute dictionary associated with edge (u, v).
get_min_max(key, mode)	Get minimum and maximum values for a specific attribute from nodes or edges.
get_node_by_position(position[, resolution])	Return node name and node_nb for node(s) on input position.
has_edge(u, v)	Returns True if the edge (u, v) is in the graph.
has_node(n)	Returns True if the graph contains the node n.
is_directed()	Returns True if graph is directed, False otherwise.
is_multigraph()	Returns True if graph is a multigraph, False otherwise.
nbunch_iter([nbunch])	Returns an iterator over nodes contained in nbunch that are also in the graph.
neighbors(n)	Returns an iterator over all neighbors of node n.
network_simplification(network_type[, ...])	Simplify a pipe network by replacing serial pipes.
new_node_number()	Return a new 4 digits node number that is not yet used in graph.
number_of_edges([u, v])	Returns the number of edges between two nodes.
number_of_nodes(node_type)	Return number of nodes for given node_type.
order()	Returns the number of nodes in the graph.
remove_building(node_number)	Remove the specified building node from the graph.
remove_dead_ends(network_type[, network_id])	Remove any nodes and edges that lead to dead ends in the network.
remove_edge(u, v)	Remove the edge between u and v.
remove_edges_from(ebunch)	Remove all edges specified in ebunch.
remove_network_node(node_number)	Remove the specified network node from the graph.
remove_node(n)	Remove node n.
remove_nodes_from(nodes)	Remove multiple nodes.
remove_self_edges(network_type[, network_id])	Remove edges with length 0 m.
remove_street_node(node_number)	Remove the specified street node from the graph.
remove_unconnected_nodes(network_type[, ...])	Remove any edges and network nodes not connected to a supply node.
rotate(degrees)	Rotate all nodes of the graph by degrees.
size([weight])	Returns the number of edges or total of all edge weights.
subgraph(nodes)	Returns a SubGraph view of the subgraph induced on nodes.
to_directed([as_view])	Returns a directed representation of the graph.
to_directed_class()	Returns the class to use for empty directed copies.
to_json([path, name, description, all_data, ...])	Save UESGraph structure to json files.
to_undirected([as_view])	Returns an undirected copy of the graph.
to_undirected_class()	Returns the class to use for empty undirected copies.
update([edges, nodes])	Update the graph using nodes/edges/graphs as input.

Attributes

adj	Graph adjacency object holding the neighbors of each node.
degree	A DegreeView for the Graph as G.degree or G.degree().
edges	An EdgeView of the Graph as G.edges or G.edges().
name	String identifier of the graph.
node
nodes	A NodeView of the Graph as G.nodes or G.nodes().
positions	Set position.

__init__()

Constructor for UESGraph class.

property node

property positions

Set position.

new_node_number()

Return a new 4 digits node number that is not yet used in graph.

Returns:

new_number – 4 digit number not yet used for nodes in graph

Return type:

int

add_network(network_type, network_id)

Add a new network of specified type.

Parameters:

• network_type (str) – Specifies the type of the new network as {‘heating’, ‘cooling’, ‘electricity’, ‘gas’, ‘others’}

• network_id (str) – Name of the new network

add_building(name=None, position=None, is_supply_heating=False, is_supply_cooling=False, is_supply_electricity=False, is_supply_gas=False, is_supply_other=False, attr_dict=None, replaced_node=None, **attr)

Add a building node to the UESGraph.

Parameters:

• name (str, int, or float) – A name for the building represented by this node. If None is given, the newly assigned node number will also be used as name.

• position (shapely.geometry.Point object) – New node’s position

• is_supply_heating (boolean) – True if the building contains a heat supply unit, False if not

• is_supply_cooling (boolean) – True if the building contains a cooling supply unit, False if not

• is_supply_electricity (boolean) – True if the building contains an electricity supply unit, False if not

• is_supply_gas (boolean) – True if the building contains a gas supply unit, False if not

• is_supply_other (boolean) – True if the building contains a supply unit for a network of network type other, False if not

• attr_dict (dictionary, optional (default= no attributes)) – Dictionary of building attributes. Key/value pairs set data associated with the building

• attr (keyword arguments, optional) – Set attributes of building using key=value

Returns:

node_number – Number of the added node in the graph

Return type:

int

remove_building(node_number)

Remove the specified building node from the graph.

Parameters:

node_number (int) – Identifier of the node in the graph

add_street_node(position, resolution=0.0001, check_overlap=True, attr_dict=None, **attr)

Add a street node to the UESGraph.

Parameters:

• position (shapely.geometry.Point) – Definition of the node position with a shapely Point object

• resolution (float) – Minimum distance between two points in m. If new position is closer than resolution to another existing node, the existing node will be returned, no new node will be created.

• check_overlap (boolean) – By default, the method checks whether the new position overlaps an existing network node. This can be skipped for performance reasons by setting check_overlap=False

• attr_dict (dictionary, optional (default= no attributes)) – Dictionary of node attributes. Key/value pairs set data associated with the node

• attr (keyword arguments, optional) – Set attributes of node using key=value

Returns:

node_number – Number of the added node in the graph

Return type:

int

remove_street_node(node_number)

Remove the specified street node from the graph.

Parameters:

node_number (int) – Identifier of the node in the graph

add_network_node(network_type, network_id='default', name=None, position=None, resolution=0.0001, check_overlap=True, attr_dict=None, **attr)

Add a network node to the UESGraph.

A network node should not be placed at positions where there is already a node of the same network or a building node.

Parameters:

• network_type (str) – Defines the network type into which to add the node. The string must be one of the network_types defined in self.network_types.

• network_id (str) – Specifies, to which network of the given type the node belongs. If no value is given, the network ‘default’ will be used. Before using a network_id, it must be added to the UESGraph with self.add_network()

• name (str, int, or float) – A name for the network junction represented by this node. If None is given, the newly assigned node number will also be used as name.

• position (shapely.geometry.Point) – Optional definition of the node position with a shapely Point object

• resolution (float) – Minimum distance between two points in m. If new position is closer than resolution to another existing node, the existing node will be returned, no new node will be created.

• check_overlap (boolean) – By default, the method checks whether the new position overlaps an existing network node. This can be skipped for performance reasons by setting check_overlap=False

• attr_dict (dictionary, optional (default= no attributes)) – Dictionary of node attributes. Key/value pairs set data associated with the node

• attr (keyword arguments, optional) – Set attributes of node using key=value

Returns:

node_number – Number of the added node in the graph

Return type:

int

remove_network_node(node_number)

Remove the specified network node from the graph.

Parameters:

node_number (int) – Identifier of the node in the graph

get_building_node(name)

Return the node number for a given building name.

Parameters:

name (str) – Name of the building

Returns:

node_number – Number of the corresponding node

Return type:

int

get_node_by_position(position, resolution=0.0001)

Return node name and node_nb for node(s) on input position.

If no node is placed on position, returns empty dictionary.

Parameters:

• position (shapely.geometry.Point) – Queried position

• resolution (float) – Minimum distance between two points in m. If position is closer than resolution to another existing node, the existing node will be returned.

Returns:

result_dict – Dictionary of nodes on input position (key: node_id, value: name)

Return type:

dict

create_subgraphs(network_type, all_buildings=True, streets=False)

Return a list of subgraphs for each network.

Parameters:

• network_type (str) – One of the network types defined in self.network_types. The subgraphs for all networks of the chosen network type will be returned

• all_buildings (boolean) – Subgraphs will contain all buildings of uesgraph when all_buildings is True. If False, only those buildings connected to a subgraph’s network will be part of the corresponding subgraph

• streets (boolean) – Subgraphs will contain streets if streets is True.

Returns:

subgraphs – List of uesgraph elements for all networks of chosen network_type

Return type:

list

from_json(path, network_type, check_overlap=False)

Import network from json input.

Parameters:

• path (str) – Path, where input files substations.json, nodes.json, pipes.json and supply.json are located.

• network_type (str) – Specifies the type of the destination network as {‘heating’, ‘cooling’, ‘electricity’, ‘gas’, ‘others’}

• check_overlap (Boolean) – By default, the method does not check whether network node positions overlap existing network nodes. For True, this check becomes active.

to_json(path=None, name=None, description='json export from uesgraph', all_data=False, prettyprint=False)

Save UESGraph structure to json files.

Parameters:

• path (str) – Path where a directory with output files will be created. If None is given, the json data will not be written to file, but only returned. This only works for format_old=False.

• name (str) – The newly created output directory at path will be named <name>HeatingUES

• description (str) – A description string that will be written to all json output files’ meta data.

• all_data (boolean) – If False, only the main data (x, y, name, node_type) will be written to the json output. If True, all node data is exported.

• prettyprint (boolean) – If True, the JSON file will use an indent of 4 spaces to pretty- print the file. By default, a more efficient output without indents will be generated

Returns:

output_data – Contents of the nodes.json file following the new format. For format_old=True the method returns None.

Return type:

dict

from_osm(osm_file, name=None, check_boundary=False, transform_positions=True)

Import buildings and streets from OpenStreetMap data in osm_file.

If available, the following attributes will be written to the imported elements:

For streets: - ‘street type’ (motorway, trunk,primary, secondary, tertiary, residential, unclassified, service, living_street, pedestrian)

For buildings - ‘position’ - ‘outlines’ - ‘area’ - ‘addr_street’ - ‘addr_housenumber’ - ‘building_levels’ - ‘building_height’ - ‘building_buildyear’ - ‘building_condition’ - ‘building_roof_shape’ - ‘comments’ - type of usage (‘amenity’, ‘shop’, ‘leisure’)

Parameters:

• osm_file (str) – Full path to osm input file

• name (str) – Name of the city for boundary check

• check_boundary (boolean) – If True, the city boundary will be extracted from the osm file and only nodes within this boundary will be accepted

• transform_positions (boolean) – By default, positions are transformed to a coordinate system that gives distances in Meter setting the origin (0, 0) at the minimum position of the graph. If transform_positions is False, the positions will remain in longitude and latitude as read from the OSM file.

Returns:

self – UESGraph for the urban energy system read from osm data

Return type:

uesgraph object

from_geojson(network_path, buildings_path, supply_path, name, save_path=None, generate_visualizations=False)

Import district heating network from GeoJSON files.

Creates a complete UESGraph model from three GeoJSON input files containing network topology, supply points, and building locations. All geometries must use CRS84 coordinate system and will be automatically transformed to a local coordinate system with distances in meters.

The import process follows these steps: 1. Process network pipes to create nodes and edges 2. Add supply points as buildings with is_supply_heating=True 3. Connect buildings to network nodes 4. Transform to local coordinate system and calculate network length

Parameters:

• network_path (str) – Path to network GeoJSON file containing LineString or MultiLineString geometries representing pipes. Optional DN property specifies nominal diameter in mm.

• buildings_path (str) – Path to buildings GeoJSON file containing Point or Polygon geometries. Must include ‘name’ property for each building.

• supply_path (str) – Path to supply points GeoJSON file containing Point geometries. Must include ‘name’ property. Points must coincide with network nodes.

• name (str) – Name identifier for this network model

• save_path (str, optional) – Directory path for saving JSON output and visualizations. If None, no files are saved.

• generate_visualizations (bool, default False) – Whether to generate and save network visualization PDFs at each processing step. Requires save_path to be specified.

Notes

• Network nodes are created at pipe endpoints and junctions

• Buildings replace network nodes at matching locations

• Supply points must exactly match existing network node positions

• Edge lengths are calculated automatically in meters

• All custom properties from GeoJSON are preserved as edge attributes

Examples

>>> graph = UESGraph()
>>> graph.from_geojson(
...     network_path='data/network.geojson',
...     buildings_path='data/buildings.geojson',
...     supply_path='data/supply.geojson',
...     name='district_1',
...     save_path='output/',
...     generate_visualizations=True
... )
>>> print(f"Total network length: {graph.network_length} m")

number_of_nodes(node_type)

Return number of nodes for given node_type.

Parameters:

node_type (str) – {‘building’, ‘street’, ‘heating’, ‘cooling’, ‘electricity’, ‘gas’, ‘other’}

Returns:

number_of_nodes – The number of nodes for the given node_type

Return type:

int

calc_network_length(network_type)

Calculate the length of all edges for given network_type.

Parameters:

network_type (str) – One of the network types defined in self.network_types

Returns:

total_length – Total length of all edges for given network_type in m

Return type:

float

calc_total_building_ground_area()

Return the sum of all available building ground areas in m**2.

Returns:

total_ground_area – Sum of all available building ground areas in m**2

Return type:

float

rotate(degrees)

Rotate all nodes of the graph by degrees.

Parameters:

degrees (float) – Value of degrees for rotation

network_simplification(network_type, network_id='default')

Simplify a pipe network by replacing serial pipes.

Parameters:

• network_type (str) – Specifies the type of the network as {‘heating’, ‘cooling’, ‘electricity’, ‘gas’, ‘others’}

• network_id (str) – Name of the network

remove_unconnected_nodes(network_type, network_id='default', max_iter=10)

Remove any edges and network nodes not connected to a supply node.

Parameters:

• network_type (str) – Specifies the type of the network as {‘heating’, ‘cooling’, ‘electricity’, ‘gas’, ‘others’}

• network_id (str) – Name of the network

• max_iter (int) – Maximum number of iterations

Returns:

removed – Names of removed network nodes

Return type:

list

remove_self_edges(network_type, network_id='default')

Remove edges with length 0 m.

Parameters

‘electricity’, ‘gas’, ‘others’}

network_idstr

Name of the network

Returns:

number_removed_edges – Number of removed network edges

Return type:

int

remove_dead_ends(network_type, network_id='default')

Remove any nodes and edges that lead to dead ends in the network.

Parameters:

• network_type (str) – Specifies the type of the network as {‘heating’, ‘cooling’, ‘electricity’, ‘gas’, ‘others’}

• network_id (str) – Name of the network

Returns:

removed – Names of removed network nodes

Return type:

list

calc_angle(a, b, output='rad')

Return the angle of a line from point a to b in rad or degrees.

Parameters:

• a (shapely.geometry.point object) –

• b (shapely.geometry.point object) –

• output (str) – Selection of output unit between ‘rad’ and ‘degrees’

Returns:

angle – Angle of a line from point a to b in rad or degrees

Return type:

float

get_min_max(key, mode)

Get minimum and maximum values for a specific attribute from nodes or edges.

Takes a UESGraph object and returns the minimum and maximum values for a given attribute key, either from all nodes or all edges depending on the specified mode.

Parameters:

• key (str) – Attribute key to look up (e.g. ‘capacity’, ‘flow’, etc.)

• mode (str) – Either ‘node’ or ‘edge’ to specify whether to look at node or edge attributes

Returns:

(minimum value, maximum value) for the specified attribute

Return type:

tuple

Raises:

• ValueError – If no values are found or mode is invalid

• KeyError – If the specified attribute key doesn’t exist for all nodes/edges