uesgraphs.uesgraph

Classes

UESGraph()

A networkx Graph enhanced for use to describe urban energy systems.
class uesgraphs.uesgraph.UESGraph[source]

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__()[source]

Constructor for UESGraph class.

property node
property positions

Set position.

new_node_number()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Remove the specified network node from the graph.

Parameters:

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

get_building_node(name)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

Rotate all nodes of the graph by degrees.

Parameters:

degrees (float) – Value of degrees for rotation

network_simplification(network_type, network_id='default')[source]

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)[source]

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')[source]

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')[source]

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')[source]

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)[source]

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