easysewer 0.0.1__py3-none-any.whl

easysewer/Link.py

@@ -0,0 +1,294 @@
+"""
+Link Management Module
+
+This module implements various types of conduits and channels that connect nodes
+in the drainage network. Supports different cross-section types and hydraulic
+characteristics.
+"""
+from .utils import *
+
+
+class Vertices:
+    """
+    Container for link vertex coordinates.
+    
+    Stores the geometry of a link's path between its endpoints.
+
+    Attributes:
+        link_name (str): Name of the associated link
+        x (list): X-coordinates of vertices
+        y (list): Y-coordinates of vertices
+    """
+    def __init__(self):
+        self.link_name = None
+        self.x = []
+        self.y = []
+
+
+class Link:
+    """
+    Base class for all hydraulic links.
+    
+    Represents a connection between two nodes in the drainage network.
+
+    Attributes:
+        name (str): Unique identifier for the link
+        vertices (Vertices): Geometric path of the link
+    """
+    def __init__(self):
+        self.name = ''
+        self.vertices = Vertices()
+
+    def __repr__(self):
+        return f'Link<{self.name}>'
+
+
+class Conduit(Link):
+    """
+    Base class for conduit-type links.
+    
+    Represents closed conduits or open channels with specific hydraulic properties.
+
+    Attributes:
+        upstream_node (str): Name of upstream node
+        downstream_node (str): Name of downstream node
+        length (float): Conduit length
+        roughness (float): Manning's roughness coefficient
+        upstream_offset (float): Offset at upstream end
+        downstream_offset (float): Offset at downstream end
+        initial_flow (float): Initial flow rate
+        maximum_flow (float): Maximum allowed flow rate
+    """
+    def __init__(self):
+        Link.__init__(self)
+        self.upstream_node = ''
+        self.downstream_node = ''
+        self.length = 0.0
+        self.roughness = 0.0
+        self.upstream_offset = 0.0
+        self.downstream_offset = 0.0
+        # optional variable
+        self.initial_flow = 0
+        self.maximum_flow = 0  # means no limit
+
+
+class ConduitCircle(Conduit):
+    def __init__(self):
+        Conduit.__init__(self)
+        self.barrels_number = 1
+        self.height = 0.0
+
+
+class ConduitFilledCircle(Conduit):
+    def __init__(self):
+        Conduit.__init__(self)
+        self.barrels_number = 1
+        self.height = 0.0
+        self.filled = 0.0
+
+
+class ConduitRectangleOpen(Conduit):
+    def __init__(self):
+        Conduit.__init__(self)
+        self.barrels_number = 1
+        self.height = 0.0
+        self.width = 0.0
+
+
+class ConduitCustom(Conduit):
+    def __init__(self):
+        Conduit.__init__(self)
+        self.barrels_number = 1
+        self.height = 0.0
+        self.curve = ''
+
+
+class LinkList:
+    def __init__(self):
+        self.data = []
+
+    def __repr__(self):
+        return f'{len(self.data)} Links'
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, key):
+        if isinstance(key, int):
+            return self.data[key]
+        elif isinstance(key, str):
+            for item in self.data:
+                if item.name == key:
+                    return item
+            raise KeyError(f"No item found with name '{key}'")
+        else:
+            raise TypeError("Key must be an integer or a string")
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __contains__(self, item):
+        return item in self.data
+
+    def add_link(self, link_type, link_information):
+        def execute(func1, func2):
+            def inner():
+                new_link = func1()
+                # basic information of conduit
+                new_link.name = link_information['name']
+                new_link.upstream_node = link_information['upstream_node']
+                new_link.downstream_node = link_information['downstream_node']
+                new_link.length = link_information['length']
+                new_link.roughness = link_information['roughness']
+                new_link.upstream_offset = link_information['upstream_offset']
+                new_link.downstream_offset = link_information['downstream_offset']
+                if 'initial_flow' in link_information:
+                    new_link.initial_flow = link_information['initial_flow']
+                if 'maximum_flow' in link_information:
+                    new_link.maximum_flow = link_information['maximum_flow']
+                # specific information of different conduit type
+                func2(new_link)
+                # add new link to link list
+                self.data.append(new_link)
+                return 0
+
+            return inner
+
+        match link_type:
+            case 'conduit_circle' | 'ConduitCircle':
+                def conduit_circle(new_link):
+                    new_link.height = link_information['height']
+                    if 'barrels_number' in link_information:
+                        new_link.barrels_number = link_information['barrels_number']
+
+                return execute(ConduitCircle, conduit_circle)()
+
+            case 'conduit_filled_circle' | 'ConduitFilledCircle':
+
+                def conduit_filled_circle(new_link):
+                    new_link.height = link_information['height']
+                    new_link.filled = link_information['filled']
+                    if 'barrels_number' in link_information:
+                        new_link.barrels_number = link_information['barrels_number']
+
+                return execute(ConduitFilledCircle, conduit_filled_circle)()
+
+            case 'conduit_rectangle_open' | 'ConduitRectangleOpen':
+                def conduit_rectangle_open(new_link):
+                    new_link.height = link_information['height']
+                    new_link.width = link_information['width']
+                    if 'barrels_number' in link_information:
+                        new_link.barrels_number = link_information['barrels_number']
+
+                return execute(ConduitRectangleOpen, conduit_rectangle_open)()
+
+            case 'conduit_custom' | 'ConduitCustom':
+                def conduit_custom(new_link):
+                    new_link.height = link_information['height']
+                    new_link.curve = link_information['curve']
+                    if 'barrels_number' in link_information:
+                        new_link.barrels_number = link_information['barrels_number']
+
+                return execute(ConduitCustom, conduit_custom)()
+
+            case _:
+                raise TypeError(f"Unknown link type, failed to add {link_information['name']}")
+
+    def read_from_swmm_inp(self, filename):
+        conduit_contents = get_swmm_inp_content(filename, '[CONDUITS]')
+        # fill in default values
+        for index, line in enumerate(conduit_contents):
+            if len(line.split()) == 7:
+                conduit_contents[index] += '  0  0'
+            elif len(line.split()) == 8:
+                conduit_contents[index] += '  0'
+        x_section = get_swmm_inp_content(filename, '[XSECTIONS]')
+        content = combine_swmm_inp_contents(conduit_contents, x_section)
+        for line in content:
+            pair = line.split()
+            dic = {'name': pair[0], 'upstream_node': pair[1], 'downstream_node': pair[2], 'length': float(pair[3]),
+                   'roughness': float(pair[4]), 'upstream_offset': float(pair[5]), 'downstream_offset': float(pair[6]),
+                   'initial_flow': float(pair[7]), 'maximum_flow': float(pair[8])}
+
+            match pair[9]:
+                case 'CIRCULAR':
+                    dic['height'] = float(pair[10])
+                    # optional variable: Barrels
+                    if len(pair) >= 15:
+                        dic['barrels_number'] = int(pair[14])
+                    self.add_link('conduit_circle', dic)
+
+                case 'FILLED_CIRCULAR':
+                    dic['height'] = float(pair[10])
+                    dic['filled'] = float(pair[11])
+                    # optional variable: Barrels
+                    if len(pair) >= 15:
+                        dic['barrels_number'] = int(pair[14])
+                    self.add_link('conduit_filled_circle', dic)
+
+                case 'RECT_OPEN':
+                    dic['height'] = float(pair[10])
+                    dic['width'] = float(pair[11])
+                    # optional variable: Barrels
+                    if len(pair) >= 15:
+                        dic['barrels_number'] = int(pair[14])
+                    self.add_link('conduit_rectangle_open', dic)
+
+                case 'CUSTOM':
+                    dic['height'] = float(pair[10])
+                    dic['curve'] = pair[11]
+                    # optional variable: Barrels
+                    if len(pair) >= 13:
+                        dic['barrels_number'] = int(pair[-1])
+                    self.add_link('conduit_custom', dic)
+        #
+        vertices_contents = get_swmm_inp_content(filename, '[VERTICES]')
+        for line in vertices_contents:
+            pair = line.split()
+            for link in self.data:
+                if link.name == pair[0]:
+                    link.vertices.x.append(float(pair[1]))
+                    link.vertices.y.append(float(pair[2]))
+                    link.vertices.link_name = pair[0]
+        return 0
+
+    def write_to_swmm_inp(self, filename):
+        with open(filename, 'a', encoding='utf-8') as f:
+            f.write('\n\n[CONDUITS]\n')
+            f.write(
+                ';;Name                          Upstream  Downstream  Length  Roughness  Up-offset Down-offset  Init_flow Max_flow\n')
+            for link in self.data:
+                f.write(
+                    f'{link.name:30}  {link.upstream_node:8}  {link.downstream_node:8}  {link.length:8.2f}  {link.roughness:8.3f}  {link.upstream_offset:8.3f}  {link.downstream_offset:8.3f}  {link.initial_flow:8.2f}  {link.maximum_flow:8.2f}\n')
+            #
+            f.write('\n\n[XSECTIONS]\n')
+            f.write(
+                ';;Name                          Shape         Geom1      Geom2      Geom3      Geom4      Barrels      (Culvert)\n')
+            for link in self.data:
+                zero = 0
+                if isinstance(link, ConduitCircle):
+                    f.write(
+                        f'{link.name:30}  CIRCULAR  {link.height:8.2f}  {zero:8}  {zero:8}  {zero:8}  {link.barrels_number:8}\n')
+                if isinstance(link, ConduitFilledCircle):
+                    f.write(
+                        f'{link.name:30}  FILLED_CIRCULAR  {link.height:8.2f}  {link.filled:8.2f}  {zero:8}  {zero:8}  {link.barrels_number:8}\n')
+                if isinstance(link, ConduitRectangleOpen):
+                    f.write(
+                        f'{link.name:30}  RECT_OPEN {link.height:8.2f}  {link.width:8.2f}  {zero:8}  {zero:8}  {link.barrels_number:8}\n')
+                if isinstance(link, ConduitCustom):
+                    f.write(
+                        f'{link.name:30}  CUSTOM    {link.height:8.2f}  {link.curve:8}  0  0  {link.barrels_number:8}\n')
+            #
+            f.write('\n\n[VERTICES]\n')
+            f.write(';;Link           X-Coord            Y-Coord\n')
+            for link in self.data:
+                if link.vertices.link_name is not None:
+                    for xi, yi in zip(link.vertices.x, link.vertices.y):
+                        f.write(f'{link.vertices.link_name}  {xi}  {yi}\n')
+        return 0
+
+    def index_of(self, link_name):
+        for index, item in enumerate(self.data):
+            if item.name == link_name:
+                return index
+        raise ValueError(f"No item found with name '{link_name}'")

easysewer/Node.py

@@ -0,0 +1,346 @@
+"""
+Node Management Module
+
+This module implements various types of nodes used in urban drainage networks including:
+- Basic nodes (junctions)
+- Outfall nodes with different boundary conditions
+- Support for node properties like elevation, coordinates, and flow characteristics
+"""
+from .utils import *
+
+
+class Node:
+    """
+    Base class for all node types in the drainage network.
+    
+    Represents a point element in the drainage network with basic properties
+    like location and elevation.
+
+    Attributes:
+        name (str): Unique identifier for the node
+        coordinate (list): [x, y] coordinates of the node
+        elevation (float): Node invert elevation
+    """
+    def __init__(self):
+        self.name = ''
+        self.coordinate = [0.0, 0.0]
+        self.elevation = 0
+
+    def __repr__(self):
+        return f'Node<{self.name}>'
+
+
+class Junction(Node):
+    """
+    Junction node type for connecting conduits.
+    
+    Represents intersection points in the drainage network where flows combine
+    or split. Includes properties for depth and ponding characteristics.
+
+    Attributes:
+        maximum_depth (float): Maximum water depth at junction
+        initial_depth (float): Initial water depth at start of simulation
+        overload_depth (float): Depth above which overflows occur
+        surface_ponding_area (float): Area available for surface ponding
+        dwf_base_value (float): Base dry weather flow value
+        dwf_patterns (list): Time patterns for dry weather flow
+        inflow (dict): Inflow characteristics and time series
+    """
+    def __init__(self):
+        Node.__init__(self)
+        self.maximum_depth = 0
+        self.initial_depth = 0
+        self.overload_depth = 0
+        self.surface_ponding_area = 0
+        #
+        # dry weather flow
+        self.dwf_base_value = 0
+        self.dwf_patterns = []
+        #
+        # inflow
+        self.inflow = None
+
+
+class Outfall(Node):
+    """
+    Base class for outfall nodes.
+    
+    Represents points where water leaves the drainage system. Supports various
+    boundary condition types through derived classes.
+
+    Attributes:
+        flap_gate (bool): Whether backflow prevention is present
+        route_to (str): Routing destination for diverted flow
+    """
+    def __init__(self):
+        Node.__init__(self)
+        self.flap_gate = False
+        self.route_to = ''
+
+
+class OutfallFree(Outfall):
+    def __init__(self):
+        Outfall.__init__(self)
+
+
+class OutfallNormal(Outfall):
+    def __init__(self):
+        Outfall.__init__(self)
+
+
+class OutfallFixed(Outfall):
+    def __init__(self):
+        Outfall.__init__(self)
+        self.stage = 0.0
+
+
+class OutfallTidal(Outfall):
+    def __init__(self):
+        Outfall.__init__(self)
+        self.tidal = ''
+
+
+class OutfallTimeseries(Outfall):
+    def __init__(self):
+        Outfall.__init__(self)
+        self.time_series = ''
+
+
+class NodeList:
+    def __init__(self):
+        self.data = []
+
+    def __repr__(self):
+        return f'{len(self.data)} Nodes'
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, key):
+        if isinstance(key, int):
+            return self.data[key]
+        elif isinstance(key, str):
+            for item in self.data:
+                if item.name == key:
+                    return item
+            raise KeyError(f"No item found with name '{key}'")
+        else:
+            raise TypeError("Key must be an integer or a string")
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __contains__(self, item):
+        return item in self.data
+
+    def add_node(self, node_type, node_information):
+        def execute(func1, func2):
+            def inner():
+                # new an object according to node_type
+                new_node = func1()
+                # add essential information
+                if 'name' in node_information:
+                    new_node.name = node_information['name']
+                else:  # if it can not find name, raise error
+                    # print('Unknown Node: Can not recognize node name')
+                    return -1
+                if 'coordinate' in node_information:
+                    new_node.coordinate = node_information['coordinate']
+                if 'elevation' in node_information:
+                    new_node.elevation = node_information['elevation']
+                # for Outfalls
+                if 'flap_gate' in node_information:
+                    new_node.flap_gate = True if node_information['flap_gate'] == 'YES' else False
+                if 'route_to' in node_information:
+                    new_node.route_to = node_information['route_to']
+                # add node_type related information
+                func2(new_node)
+                # update node_list
+                self.data.append(new_node)
+                return 0
+
+            return inner
+
+        match node_type:
+            case 'junction' | 'Junction':
+                def junction_type(new_node):
+                    if 'maximum_depth' in node_information:
+                        new_node.maximum_depth = node_information['maximum_depth']
+                    if 'initial_depth' in node_information:
+                        new_node.initial_depth = node_information['initial_depth']
+                    if 'overload_depth' in node_information:
+                        new_node.overload_depth = node_information['overload_depth']
+                    if 'surface_ponding_area' in node_information:
+                        new_node.surface_ponding_area = node_information['surface_ponding_area']
+                    if 'dwf_base_value' in node_information:
+                        new_node.dwf_base_value = node_information['dwf_base_value']
+                    if 'dwf_patterns' in node_information:
+                        new_node.dwf_patterns = node_information['dwf_patterns']
+
+                return execute(Junction, junction_type)()
+
+            case 'outfall_free' | 'OutfallFree':
+                def outfall_free_type(_):
+                    pass
+
+                return execute(OutfallFree, outfall_free_type)()
+
+            case 'outfall_normal' | 'OutfallNormal':
+                def outfall_normal_type(_):
+                    pass
+
+                return execute(OutfallNormal, outfall_normal_type)()
+
+            case 'outfall_fixed' | 'OutfallFixed':
+                def outfall_fixed_type(new_node):
+                    if 'stage' in node_information:
+                        new_node.stage = node_information['stage']
+
+                return execute(OutfallFixed, outfall_fixed_type)()
+
+            case 'outfall_tidal' | 'OutfallTidal':
+                def outfall_tidal_type(new_node):
+                    if 'tidal' in node_information:
+                        new_node.tidal = node_information['tidal']
+
+                return execute(OutfallTidal, outfall_tidal_type)()
+
+            case 'outfall_time_series' | 'OutfallTimeseries':
+                def outfall_time_series_type(new_node):
+                    if 'time_series' in node_information:
+                        new_node.time_series = node_information['time_series']
+
+                return execute(OutfallTimeseries, outfall_time_series_type)()
+
+            case _:
+                raise TypeError(f"Unknown node type, failed to add {node_information['name']}")
+
+    def read_from_swmm_inp(self, filename):
+        junction_contents = get_swmm_inp_content(filename, '[JUNCTIONS]')
+        coordinates = get_swmm_inp_content(filename, '[COORDINATES]')
+        outfall_contents = get_swmm_inp_content(filename, '[OUTFALLS]')
+        dwf_contents = get_swmm_inp_content(filename, '[DWF]')
+        inflow_contents = get_swmm_inp_content(filename, '[INFLOWS]')
+
+        # coordinate list
+        coordinates_dic = {}
+        for line in coordinates:
+            keys = line.split()
+            coordinates_dic[keys[0]] = [float(keys[1]), float(keys[2])]
+        # process junctions
+        for line in junction_contents:
+            pair = line.split()
+            dic = {'name': pair[0], 'coordinate': [0.0, 0.0], 'elevation': float(pair[1]),
+                   'maximum_depth': float(pair[2]), 'initial_depth': float(pair[3]),
+                   'overload_depth': float(pair[4]), 'surface_ponding_area': float(pair[5])}
+            dic['coordinate'] = coordinates_dic[dic['name']]
+            self.add_node('junction', dic)
+        # process outfalls
+        for line in outfall_contents:
+            pair = line.split()
+            dic = {'name': pair[0], 'coordinate': [0.0, 0.0], 'elevation': float(pair[1])}
+            dic['coordinate'] = coordinates_dic[dic['name']]
+            #
+            if pair[-1] == 'YES':
+                dic['flap_gate'] = 'YES'
+            elif pair[-1] == 'NO':
+                dic['flap_gate'] = 'NO'
+            else:
+                dic['flap_gate'] = pair[-2]
+                dic['route_to'] = pair[-1]
+            #
+            match pair[2]:
+                case 'FREE':
+                    self.add_node('outfall_free', dic)
+                case 'NORMAL':
+                    self.add_node('outfall_normal', dic)
+                case 'FIXED':
+                    dic['stage'] = float(pair[2])
+                    self.add_node('outfall_fixed', dic)
+                case 'TIDAL':
+                    dic['tidal'] = float(pair[2])
+                    self.add_node('outfall_tidal', dic)
+                case 'TIMESERIES':
+                    dic['time_series'] = float(pair[2])
+                    self.add_node('outfall_time_series', dic)
+                case _:
+                    pass
+        # process DWF
+        for line in dwf_contents:
+            pair = line.split()
+            for node in self.data:
+                if node.name == pair[0]:
+                    node.dwf_base_value = pair[2]
+                    for pattern in pair[3::]:
+                        node.dwf_patterns.append(pattern)
+        # process inflow
+        for line in inflow_contents:
+            pair = line.split()
+            if pair[1] != 'FLOW':
+                raise Exception('Unsupported inflow type, only FLOW is accepted.')
+            for node in self.data:
+                if node.name == pair[0]:
+                    result = {'time_series': pair[2], 'type': pair[3], 'm_factor': float(pair[4]),
+                              's_factor': float(pair[5]), 'baseline': float(pair[6]), 'pattern': pair[7]}
+                    node.inflow = result
+        return 0
+
+    def write_to_swmm_inp(self, filename):
+        with open(filename, 'a', encoding='utf-8') as f:
+            f.write('\n\n[JUNCTIONS]\n')
+            f.write(';;Name  Elevation  MaxDepth  InitDepth  SurDepth  Ponding\n')
+            for node in self.data:
+                if isinstance(node, Junction):
+                    f.write(
+                        f'{node.name:8}  {node.elevation:8.3f}  {node.maximum_depth:8.3f}  {node.initial_depth:8.3f}  {node.overload_depth:8.3f}  {node.surface_ponding_area:8.3f}\n')
+            #
+            f.write('\n\n[OUTFALLS]\n')
+            f.write(';;Name  Elevation  Type  //  Gated  RouteTo\n')
+            for node in self.data:
+                if isinstance(node, OutfallFree):
+                    msg = 'YES' if node.flap_gate else 'NO'
+                    f.write(f'{node.name:8}  {node.elevation:8.3f}    FREE    {msg:8}  {node.route_to}\n')
+                if isinstance(node, OutfallNormal):
+                    msg = 'YES' if node.flap_gate else 'NO'
+                    f.write(f'{node.name:8}  {node.elevation:8.3f}    NORMAL    {msg:8}  {node.route_to}\n')
+                if isinstance(node, OutfallFixed):
+                    msg = 'YES' if node.flap_gate else 'NO'
+                    f.write(
+                        f'{node.name:8}  {node.elevation:8.3f}    FIXED    {node.stage:8}  {msg}  {node.route_to}\n')
+                if isinstance(node, OutfallTidal):
+                    msg = 'YES' if node.flap_gate else 'NO'
+                    f.write(
+                        f'{node.name:8}  {node.elevation:8.3f}    TIDAL    {node.tidal:8}  {msg}  {node.route_to}\n')
+                if isinstance(node, OutfallTimeseries):
+                    msg = 'YES' if node.flap_gate else 'NO'
+                    f.write(
+                        f'{node.name:8}  {node.elevation:8.3f}    TIMESERIES    {node.time_series:8}  {msg}  {node.route_to}\n')
+            #
+            f.write('\n\n[COORDINATES]\n')
+            f.write(';;Name  X-Coord  Y-Coord\n')
+            for node in self.data:
+                f.write(f'{node.name:8}  {node.coordinate[0]:8.2f}  {node.coordinate[1]:8.2f}\n')
+            #
+            f.write('\n\n[DWF]\n')
+            f.write(';;Node           Constituent      Baseline   Patterns  \n')
+            for node in self.data:
+                if isinstance(node, Junction):
+                    if node.dwf_base_value != 0:
+                        string = ' '.join(node.dwf_patterns)
+                        f.write(f'{node.name}  FLOW  {node.dwf_base_value}  {string}\n')
+            #
+            f.write('\n\n[INFLOWS]\n')
+            f.write(';;Node           Constituent      Time Series      Type     Mfactor  Sfactor  Baseline Pattern\n')
+            for node in self.data:
+                if isinstance(node, Junction):
+                    if node.inflow is not None:
+                        res = [str(i) for i in list(node.inflow.values())]
+                        res = '    '.join(res)
+                        f.write(f'{node.name}  FLOW  {res}  \n')
+        return 0
+
+    def index_of(self, node_name):
+        for index, item in enumerate(self.data):
+            if item.name == node_name:
+                return index
+        raise ValueError(f"No item found with name '{node_name}'")