sir3stoolkit.mantle package

Submodules

sir3stoolkit.mantle.alternative_models module

Created on Weg Sep 01 14:04:43 2025

This module implements the generation of SIR 3S models in alternative model formats such as pandapipes or nx-Graphs.

@author: Jablonski

class sir3stoolkit.mantle.alternative_models.SIR3S_Model_Alternative_Models

Bases: SIR3S_Model_Dataframes

This class is supposed to extend the Dataframes class that extends the general SIR3S_Model class with the possibility of using alternative District Heating models such as pandapipes.

SIR_3S_to_nx_graph()

Build a directed NetworkX graph from SIR 3S model.

Returns:

Directed graph with nodes and edges populated from SIR 3S model.

Return type:

nx.DiGraph

SIR_3S_to_pandapipes()

Converts the currently open SIR 3S network into a pandapipes network.

This function creates a pandapipes network that mirrors the structure of the SIR 3S network, including junctions (nodes), pipes, and external sources/sinks. Only elements of type Node and Pipe are included; FWVB (district heating consumers) are excluded.

Returns:

A pandapipes network object containing: - Junctions with metadata and result values (pressure, temperature, flow). - Pipes with geometry and physical parameters. - External grids (sources) and sinks based on node type and flow direction.

Return type:

pandapipes.pandapipesNet

add_properties_to_graph(G: DiGraph, element_type: str, properties: List[str], timestamp: str | None = None) → DiGraph

Enrich nodes and edges in G with additional attributes by joining on ‘tk’.

Parameters:

• G (nx.DiGraph) – The already-built graph where nodes/edges have at least a ‘tk’ attribute.

• element_type (str) – The element type to filter by (must match df[element_type_col] and edge attr “element type”).

• properties (list of str) – Column names from the dataframe to add as attributes

• timestamp (str) – Timestamp used for adding result properties. If None, STAT will be used.

Returns:

The same graph instance with enriched attributes.

Return type:

nx.DiGraph

get_object_type_enum(element_type: str)

Return the enum member from self.ObjectTypes corresponding to the given element_type string.

Parameters:

element_type (str) – Name of the element type (e.g., ‘Node’, ‘Pipe’).

Return type:

Enum member from self.ObjectTypes if found, else None.

sir3stoolkit.mantle.dataframes module

Created on Fri Aug 29 09:22:31 2025

This module implements interactions between SIR 3S and pandas dataframes. You can obtain pandas dfs with meta- or resultdata, insert nodes and pipes via a df, etc.

@author: Jablonski

class sir3stoolkit.mantle.dataframes.SIR3S_Model_Dataframes

Bases: SIR3S_Model

This class is supposed to extend the general SIR3S_Model class with the possibility of using pandas dataframes when working with SIR 3S. Getting dataframes, inserting elements via dataframes, running algorithms on dataframes should be made possible.

AddNodesAndPipes(dfXL)

Takes a dataframe with each row representing one pipe and adds it to the model. Only dfXL This function should be moved to Dataframes.py to create a general module for working with Dataframes in SIR 3S.

Check_Node_Name_Duplicates(name)

class DataFrames(df_node: 'pd.DataFrame' = <factory>, df_pipe: 'pd.DataFrame' = <factory>)

Bases: object

df_node: DataFrame

df_pipe: DataFrame

Get_Node_Tks_From_Pipe(pipe_tk)

Get_Pipe_Tk_From_Nodes(fkKI, fkKK, Order=True)

Merge_Nodes(tk1, tk2)

Node_on_Node()

VL_or_RL(KVR)

apply_metadata_property_updates(element_type: Enum, updates_df: DataFrame, properties_new: List[str] | None = None, tag: str | None = '_new') → DataFrame

WORK IN PROGRESS Apply metadata updates for a single property using a DataFrame with keys and new values.

Expects: - One key column (default: ‘tk’), and - Exactly one column named ‘<metadata_property>_new’ (or pass property_name to target one explicitly).

Parameters:

• element_type (Enum) – The element type to update (e.g., self.ObjectTypes.Pipe).

• updates_df (pd.DataFrame) – Input with at least: - key column (default ‘tk’), and - one ‘<property>_new’ column (e.g., ‘diameter_mm_new’).

• property_name (Optional[str], default None) – If given, we will look for the column f”{property_name}_new”. If None, we auto-detect a single ‘*_new’ column.

• on (str, default 'tk') – Name of the key column in updates_df. If it’s the index, it will be reset.

• create_missing (bool, default False) – If True, allow creating metadata rows that don’t exist yet (your set-logic decides how).

• dry_run (bool, default False) – If True, do NOT apply; just return a normalized summary of what would be changed.

• allow_na (bool, default True) – If False, rows with NaN in the ‘<property>_new’ column will be dropped (skipped).

Returns:

A summary dataframe with columns: [‘tk’, ‘property’, ‘new_value’] (+ ‘status’ when dry_run) representing the intended updates.

Return type:

pd.DataFrame

generate_dataframes()

WORK IN PROGRESS Manually generate and populate all relevant dataframes.

Inlcude optional param with ElemenTypes to only create certain dataframes

generate_element_metadata_dataframe(element_type: Enum, tks: List[str] | None = None, properties: List[str] | None = None, geometry: bool | None = False, end_nodes: bool | None = False, filter_container_tks: List[str] | None = None, element_type_col: bool | None = False) → DataFrame | GeoDataFrame

Generate a dataframe with metadata (static) properties for all devices of a given element type.

Parameters:

• element_type (Enum The element type (e.g., self.ObjectTypes.Node).)

• properties (list[str], optional) – If properties=None => All available properties will be used If properties=[] => No properties will be used

• geometry (bool, optional) – If True, includes geometric information for each element in the dataframe. Note that this is still a regular DataFrame no GeoDataFrame, to convert it you need a crs values. Adds a ‘geometry’ column containing spatial data (WKT represenation eg. POINT (x y)) Default is False.

• end_nodes (bool, optional) – If True and supported by the element type, includes tks of end nodes as cols (fkKI, fkKK, fkKI2, fkKK2) in the dataframe. Default is False.

• filter_container_tks (list[str], optional) – List of tks of containers to use element from. Elements from other containers are not included.

• element_type_col (bool, option) – If true, a column indicating the element type will be added. Useful if df is later merged.

Returns:

Dataframe with one row per device (tk) and columns for requested metadata properties, geometry and end nodes. Columns: [“tk”, <metadata_props>]

Return type:

pd.DataFrame

generate_element_results_dataframe(element_type: Enum, tks: List[str] | None = None, properties: List[str] | None = None, timestamps: List[str] | None = None, filter_container_tks: str | None = None, use_vector_results: bool | None = False) → DataFrame

Generate a dataframe with RESULT (time-dependent) properties for all devices and timestamps.

Parameters:

• element_type (Enum or str) – The element type (e.g., self.ObjectTypes.Node).

• properties (list[str], optional) – List of RESULT property names (vectors) to include. If None, includes ALL available result properties.

• timestamps (list[Union[str, int]], optional) –

  List of timestamps to include. Can be: - List of timestamp strings (e.g., [“2025-09-25 00:00:00.000 +02:00”, “2025-09-25 00:00:01.000 +02:00”, ‘2025-09-25 00:00:05.000 +02:00’]) - List of integer indices (e.g., [0, 7, -1]), where:

  • 0 refers to the first simulation timestamp

  • 7 refers to the seventh simulation timestamp

  • -1 refers to the last available timestamp

• filter_container_tks (list[str], optional) – List of tks of containers to use element from. Elements from other containers are not included.

Returns:

Dataframe with one row per timestamp (datatype float) and MultiIndex columns: - Level 0: tk (device ID) - Level 1: name (device name) - Level 2: end_nodes (tuple of connected node IDs as string) - Level 3: property (result vector name)

Return type:

pd.DataFrame

generate_hydraulic_edge_dataframe() → DataFrame

Generates a pandas dataframe containing all edges that are part of the hydraulic model (eg. pipes, valves, compressors, etc.).

get_EPSG() → Tuple[str]

Returns SRID, SRID and combined String. For example: (‘25832’, ‘1571’, ‘25832-1571’)

insert_dfPipes(dfPipes)

Takes a dataframe with each row representing one pipe and adds it to the model. The dataframe needs minimum of cols: geometry (LINESTRING), MATERIAL (str), DN (int), KVR (int)

sir3stoolkit.mantle.mantle module

Created on Thu Okt 7 13:44:32 2025

This module is a collector for all mantle implementations. And provides the SIR3S_Model_Mantle() class that contains the functions from all other classes defined in the mantle.

@author: Jablonski

class sir3stoolkit.mantle.mantle.SIR3S_Model_Mantle

Bases: SIR3S_Model_Alternative_Models, SIR3S_Model_Dataframes, SIR3S_Model_Plotting

sir3stoolkit.mantle.plotting module

Created on Thu Okt 7 13:39:13 2025

This module implements general plotting functions for SIR 3S applications. TODO: AGSN, Time Curves, Network Color Diagram

@author: Jablonski

class sir3stoolkit.mantle.plotting.SIR3S_Model_Plotting

Bases: SIR3S_Model

plot_node_layer(ax=None, gdf=None, *, size_scaling_col: str | None = None, color_mixing_col: str | None = None, attribute: str | None = None, colors=('darkgreen', 'magenta'), legend_fmt: str | None = None, legend_values: list[float] | None = None, size_vmin: float | None = None, size_vmax: float | None = None, color_vmin: float | None = None, color_vmax: float | None = None, query: str | None = None, marker_style: str = 'o', marker_size_factor: float = 1000.0, zorder: float | None = None)

Plot point nodes with separate size and color scaling.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axis to plot into. If None, uses current axes (plt.gca()).

• gdf (pandas.DataFrame or geopandas.GeoDataFrame) – Input with a ‘geometry’ column of shapely geometries.

• size_scaling_col (str, optional) – Column used to scale marker sizes (numeric). If None, uses attribute if provided; otherwise constant size.

• color_mixing_col (str, optional) – Column used to color markers (numeric). If None, uses attribute if provided; otherwise a constant color.

• attribute (str, optional) – Legacy single column used for both size and color if the specific columns are not provided.

• colors (tuple[str, str], optional) – Two colors to build a linear segmented colormap.

• legend_fmt (str, optional) – Legend label format, default: f”{color_col} {{:.4f}}”.

• legend_values (list[float], optional) – Explicit legend tick values; default: 5 linear steps.

• size_vmin (float, optional) – Bounds for size normalization; defaults to data min/max.

• size_vmax (float, optional) – Bounds for size normalization; defaults to data min/max.

• color_vmin (float, optional) – Bounds for color normalization; defaults to data min/max.

• color_vmax (float, optional) – Bounds for color normalization; defaults to data min/max.

• query (str, optional) – Pandas query string to filter rows before plotting.

• marker_style (str, optional) – Matplotlib marker style, default ‘o’.

• marker_size_factor (float, optional) – Factor applied after size normalization, default 1000.0.

• zorder (float, optional) – Z-order for drawing.

Returns:

Legend patches based on the color scaling column; None if constant color.

Return type:

list[matplotlib.patches.Patch] or None

plot_pipe_layer(ax=None, gdf=None, *, width_scaling_col: str | None = None, color_mixing_col: str | None = None, attribute: str | None = None, colors=('darkgreen', 'magenta'), legend_fmt: str | None = None, legend_values: list[float] | None = None, width_vmin: float | None = None, width_vmax: float | None = None, color_vmin: float | None = None, color_vmax: float | None = None, query: str | None = None, line_width_factor: float = 10.0, zorder: float | None = None)

Plot line geometries with separate width and color scaling.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axis to plot into. If None, uses current axes (plt.gca()).

• gdf (pandas.DataFrame or geopandas.GeoDataFrame) – Input with a ‘geometry’ column of shapely LineString/MultiLineString.

• width_scaling_col (str, optional) – Column used to scale line widths (numeric). If None, uses attribute if provided; otherwise constant width.

• color_mixing_col (str, optional) – Column used to color lines (numeric). If None, uses attribute if provided; otherwise a constant color.

• attribute (str, optional) – Legacy single column used for both width and color if the specific columns are not provided.

• colors (tuple[str, str], optional) – Two colors to build a linear segmented colormap.

• legend_fmt (str, optional) – Legend label format, default: f”{color_col} {{:.4f}}”.

• legend_values (list[float], optional) – Explicit legend tick values; default: 5 linear steps.

• width_vmin (float, optional) – Bounds for width normalization; defaults to data min/max.

• width_vmin – Bounds for width normalization; defaults to data min/max.

• color_vmin (float, optional) – Bounds for color normalization; defaults to data min/max.

• color_vmax (float, optional) – Bounds for color normalization; defaults to data min/max.

• query (str, optional) – Pandas query string to filter rows before plotting.

• line_width_factor (float, optional) – Factor applied after width normalization, default 10.0.

• zorder (float, optional) – Z-order for drawing.

Returns:

Legend patches based on the color scaling column; None if constant color.

Return type:

list[matplotlib.patches.Patch] or None

Module contents