### Install swmmio Source: https://swmmio.readthedocs.io/en/latest/_sources/index.ipynb.txt Install the swmmio package using pip. ```bash pip install swmmio ``` -------------------------------- ### Load SWMM Model and Get Links Source: https://swmmio.readthedocs.io/en/latest/_sources/usage/getting_started.ipynb.txt Load an example SWMM model provided by swmmio and display its links as a pandas DataFrame. This is useful for inspecting network connectivity and properties. ```python import swmmio # Load the example model model = swmmio.Model("swmmio/example_models/Example.inp") # Get the links as a DataFrame model.links ``` -------------------------------- ### Access Nodes Dataframe with Example Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Collects and organizes all node objects in the model into a pandas DataFrame. Includes an example showing how to access the 'InvertElev' column for nodes. ```python @property def nodes(self, bbox=None): """ Collect all useful and available data related model nodes and organize in one dataframe. :return: dataframe containing all node objects in the model :rtype: pd.DataFrame >>> from swmmio.examples import jersey >>> jersey.nodes.dataframe['InvertElev'] Name J3 6.547 1 17.000 2 17.000 3 16.500 4 16.000 5 15.000 J2 13.000 J4 0.000 J1 13.392 Name: InvertElev, dtype: float64 """ # check if this has been done already and return that data accordingly if self._nodes_df is not None and bbox == self.bbox: return self._nodes_df ``` -------------------------------- ### Access Pumps Dataframe with Example Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Retrieves a pandas DataFrame containing all model pumps. Includes an example demonstrating how to access pump curve and initial status. ```python @property def pumps(self): """ Collect all useful and available data related model pumps and organize in one dataframe. :return: dataframe containing all pumps objects in the model :rtype: pd.DataFrame >>> import swmmio >>> from swmmio.tests.data import MODEL_FULL_FEATURES_XY >>> model = swmmio.Model(MODEL_FULL_FEATURES_XY) >>> pumps = model.pumps.dataframe >>> pumps[['PumpCurve', 'InitStatus']] #doctest: +NORMALIZE_WHITESPACE PumpCurve InitStatus Name C2 P1_Curve ON """ self._pumps_df = Links(model=self, **COMPOSITE_OBJECTS['pumps']) return self._pumps_df ``` -------------------------------- ### Access All Links Dataframe with Example Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Creates a DataFrame containing all link objects (conduits, pumps, weirs, orifices) in the model. Provides an example of accessing a specific link's properties. ```python @property def links(self): """ Create a DataFrame containing all link objects in the model including conduits, pumps, weirs, and orifices. :return: dataframe containing all link objects in the model :rtype: pd.DataFrame Examples --------- >>> from swmmio.examples import philly >>> philly.links.dataframe.loc['J1-025.1'] #doctest: +NORMALIZE_WHITESPACE InletNode J1-025 OutletNode J1-026 Length 309.456216 Roughness 0.014 InOffset 0 OutOffset 0.0 InitFlow 0 MaxFlow 0 Shape CIRCULAR Geom1 1.25 Geom2 0 Geom3 0 Geom4 0 Barrels 1 coords [(2746229.223, 1118867.764), (2746461.473, 1118663.257)] Name: J1-025.1, dtype: object """ if self._links_df is not None: return self._links_df df = Links(model=self, **COMPOSITE_OBJECTS['links']) self._links_df = df return df ``` -------------------------------- ### Accessing INP Report Section Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Demonstrates how to get the report section of an INP file. ```python >>> from swmmio.examples import jersey >>> jersey.inp.report #doctest: +NORMALIZE_WHITESPACE Status Param INPUT YES CONTROLS YES SUBCATCHMENTS NONE NODES ALL LINKS NONE ``` -------------------------------- ### Accessing INP Evaporation Section Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Illustrates how to get the evaporation section of an INP file. ```python >>> from swmmio.examples import walnut >>> walnut.inp.evaporation #doctest: +NORMALIZE_WHITESPACE Value Key CONSTANT 0.0 DRY_ONLY NO ``` -------------------------------- ### Initial SWMM Model Plotting Source: https://swmmio.readthedocs.io/en/latest/usage/making_art_with_swmm.html Plots the links and nodes of the SWMM 'jersey' example model. Hides axes for artistic presentation. ```python import numpy as np import pandas as pd import swmmio from swmmio.examples import jersey from swmmio.utils.functions import rotate_model from swmmio.utils.spatial import centroid_and_bbox_from_coords ax = jersey.links.geodataframe.plot(linewidth=jersey.links.dataframe['Geom1'], capstyle='round') jersey.nodes.geodataframe.plot('MaxDepth', ax=ax, markersize='InvertElev', zorder=2) # hide the axes since we're making art ax.set_axis_off() ``` -------------------------------- ### Load SWMM Model and Get Links DataFrame Source: https://swmmio.readthedocs.io/en/latest/usage/getting_started.html Instantiate a swmmio Model object and retrieve the DataFrame for links. This is useful for inspecting link properties. ```python from swmmio.tests.data import MODEL_FULL_FEATURES_PATH import swmmio # instantiate a model object model = swmmio.Model(MODEL_FULL_FEATURES_PATH) # get the data related to links model.links.dataframe ``` -------------------------------- ### Get Groundwater DataFrame Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Retrieves the 'Groundwater' section of the INP file as a pandas DataFrame. It requires the 'swmmio.examples.groundwater' module. If the DataFrame has not been loaded, it will be loaded from the file. ```python >>> from swmmio.examples import groundwater >>> groundwater.inp.groundwater.loc['1'] #doctest: +NORMALIZE_WHITESPACE Aquifer 1.0 Node 2.0 Esurf 6.0 A1 0.1 B1 1.0 A2 0.0 B2 0.0 A3 0.0 Dsw 0.0 ``` -------------------------------- ### Get Aquifers DataFrame Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Retrieves the 'Aquifers' section of the INP file as a pandas DataFrame. It requires the 'swmmio.examples.groundwater' module. If the DataFrame has not been loaded, it will be loaded from the file. ```python >>> from swmmio.examples import groundwater >>> groundwater.inp.aquifers.loc['1'] #doctest: +NORMALIZE_WHITESPACE Por 0.500 WP 0.150 FC 0.300 Ksat 0.100 Kslope 12.000 Tslope 15.000 ETu 0.350 ETs 14.000 Seep 0.002 Ebot 0.000 Egw 3.500 Umc 0.400 Name: 1, dtype: float64 ``` -------------------------------- ### Get Streets DataFrame Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Retrieves the streets section of the SWMM input file as a pandas DataFrame. This example shows how to access specific columns from the DataFrame. ```python >>> from swmmio.examples import streets >>> streets.inp.streets[['Tcrown', 'Hcurb']] #doctest: +NORMALIZE_WHITESPACE ``` -------------------------------- ### Initialize BuildInstructions from File Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/version_control/inp.html Creates a BuildInstructions object by reading change instructions and metadata from a specified file. Useful for loading previously saved build instructions. ```python from swmmio.version_control.inp import BuildInstructions # Assuming 'build_instructions.txt' contains the build instructions build_instr = BuildInstructions(build_instr_file='build_instructions.txt') ``` -------------------------------- ### Model Initialization with Parameters Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Initialize a swmmio.Model object by specifying the INP file path, coordinate reference system (CRS), and whether to include report file data. ```python def __init__(self, in_file_path, crs=None, include_rpt=True): """ Initialize a swmmio.Model object by pointing it to a local INP file or a URL to a remote INP file. Parameters ---------- in_file_path : str Path to local INP file or URL to remote INP file crs : str, optional String representation of a coordinate reference system, by default None include_rpt : bool, optional whether to include data from an RPT (if an RPT exists), by default True """ self.crs = None inp_path = None # if the input is a URL, download it to a temp location ``` -------------------------------- ### Find Byte Range of Section in Text File Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/utils/text.html Locates the start and end byte positions of a section in a text file, identified by a starting string. The end is determined by the first blank line encountered after the start string, provided it's more than 100 bytes from the start. ```python import re import os from collections import OrderedDict def find_byte_range_of_section(path, start_string): ''' returns the start and end "byte" location of substrings in a text file ''' with open(path) as f: start = None end = None l = 0 # line bytes index for line in f: if start and line.strip() == "" and (l - start) > 100: # LOGIC: if start exists (was found) and the current line # length is 3 or less (length of /n ) and we're more than # 100 bytes from the start location then we are at the first # "blank" line after our start section (aka the end of the # section) end = l break if (start_string in line) and (not start): start = l # increment length (bytes?) of current position l += len(line) + len("\n") return [start, end] ``` -------------------------------- ### Initialize swmmio.Model from INP file Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_model.html Initialize a swmmio.Model object by providing the path to an INP file. This allows access to the model's input data. ```python >>> # initialize a model object by passing the path to an INP file >>> from swmmio.tests.data import MODEL_FULL_FEATURES_XY >>> m = Model(MODEL_FULL_FEATURES_XY) >>> # access sections of inp via the Model.inp object >>> m.inp.junctions InvertElev MaxDepth InitDepth SurchargeDepth PondedArea Name J3 6.547 15 0 0 0 1 17.000 0 0 0 0 2 17.000 0 0 0 0 3 16.500 0 0 0 0 4 16.000 0 0 0 0 5 15.000 0 0 0 0 J2 13.000 15 0 0 0 >>> m.inp.coordinates X Y Name J3 2748073.306 1117746.087 1 2746913.127 1118559.809 2 2747728.148 1118449.164 3 2747242.131 1118656.381 4 2747345.325 1118499.807 5 2747386.555 1118362.817 J2 2747514.212 1118016.207 J4 2748515.571 1117763.466 J1 2747402.678 1118092.704 ``` -------------------------------- ### options Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the options section of the INP file. This property returns a pandas DataFrame representing the options and allows for modification by assigning a new DataFrame. ```APIDOC ## options ### Description Get/set options section of the INP file. ### Method GET/SET ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **df** (pandas.DataFrame) - Required - The DataFrame to set as the options section. ### Request Example ```python # Example for setting options model.inp.options = new_options_df ``` ### Response #### Success Response (200) - **pandas.DataFrame** - The options section of the INP file. #### Response Example ```python # Example for getting options print(model.inp.options) ``` ``` -------------------------------- ### Get INP Sections Details Source: https://swmmio.readthedocs.io/en/latest/reference/utils/text.html Parses an INP file to create a dictionary of section headers and their details. Helps in understanding the structure of SWMM input files. ```python from swmmio.tests.data import MODEL_FULL_FEATURES_XY headers = get_inp_sections_details(MODEL_FULL_FEATURES_XY) [header for header, cols in headers.items()][:4] headers['SUBCATCHMENTS']['columns'] ``` -------------------------------- ### Creating INP Build Instructions Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/version_control/inp.html Generates a build instructions file detailing the differences between two SWMM INP files. This file can be used to programmatically update a baseline model. ```python allsections_a = get_inp_sections_details(inpA) modela = swmmio.Model(inpA) modelb = swmmio.Model(inpB) # create build insructions folder if not os.path.exists(path): os.makedirs(path) filepath = os.path.join(path, filename) + '.txt' problem_sections = ['TITLE', 'CURVES', 'TIMESERIES', 'RDII', 'HYDROGRAPHS'] with open(filepath, 'w') as newf: # write meta data metadata = { # 'Baseline Model':modela.inp.path, # 'ID':filename, 'Parent Models': { 'Baseline': {inpA: vc_utils.modification_date(inpA)}, 'Alternatives': {inpB: vc_utils.modification_date(inpB)} }, 'Log': {filename: comments} } # print metadata vc_utils.write_meta_data(newf, metadata) ``` -------------------------------- ### timeseries Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the timeseries data from the SWMM model. When getting, it returns a pandas DataFrame. When setting, it accepts a pandas DataFrame. ```APIDOC ## timeseries ### Description Get or set the timeseries data from the SWMM model. When getting, it returns a pandas DataFrame. When setting, it accepts a pandas DataFrame. ### Method GET / SET ### Parameters #### Request Body (Setter) - **df** (pandas.DataFrame) - Required - The DataFrame to set as timeseries data. ### Response (Getter) - **_timeseries_df** (pandas.DataFrame) - The timeseries data as a DataFrame. ``` -------------------------------- ### extract_section_of_file Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/utils/text.html Extracts a portion of a file located between specified start and end strings. It can handle multiple start strings and ignores lines designated as comments. ```APIDOC ## extract_section_of_file ### Description Extract a portion of a file found between one or more start strings and the first encountered end string. ### Parameters * **file_path** (str) - Required - Path to the source file. * **start_strings** (str or list of str) - Required - String or list of strings from which to start extracting. * **end_strings** (str or list of str) - Required - String or list of strings at which to stop extracting. * **comment** (str, optional) - String used to ignore parts of the source file. Defaults to ';'. * **kwargs** - Other keyword arguments. ### Returns * **str** - String extracted from source file. ### Examples ```python from swmmio.tests.data import MODEL_FULL_FEATURES_XY s = extract_section_of_file(MODEL_FULL_FEATURES_XY, '[EVAPORATI', '[', comment=None) print(s.strip()) ``` ### Example Output ``` [EVAPORATION] ;;Data Source Parameters ;;-------------- ---------------- CONSTANT 0.0 DRY_ONLY NO ``` ``` -------------------------------- ### Running a Single SWMM Model from Command Line Source: https://swmmio.readthedocs.io/en/latest/usage/getting_started.html Execute a single SWMM5 model using the swmmio module from the command line. Specify the path to the .inp file. ```bash python -m swmmio --run path/to/mymodel.inp ``` -------------------------------- ### swmmio.core.Model Constructor Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_model.html Initializes a swmmio.Model object. It can be initialized by providing the path to a directory containing an INP file (and optionally an RPT file with a matching filename) or by directly providing the path to an .inp file. The CRS can also be optionally specified. ```APIDOC ## Class: swmmio.core.Model ### Description Represents a complete SWMM model, incorporating its INP and RPT files and data. It allows initialization by pointing to a directory with an INP file or directly to an .inp file. Optionally, a Coordinate Reference System (CRS) can be provided, and the inclusion of the RPT file can be controlled. ### Parameters * `_in_file_path_` (string) - Path to the SWMM INP file or directory containing the INP file. * `_crs` (string, optional) - The Coordinate Reference System for the model data. * `_include_rpt` (bool, optional) - Whether to include data from the RPT file. Defaults to True. ### Example ```python # Initialize a model object by passing the path to an INP file from swmmio.tests.data import MODEL_FULL_FEATURES_XY m = Model(MODEL_FULL_FEATURES_XY) # Initialize a model object by passing the path to a directory # m = Model('/path/to/model/directory/') ``` ``` -------------------------------- ### Build INP File from Baseline and Instructions Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/version_control/inp.html Constructs a complete SWMM INP file by applying the committed build instructions to a baseline INP model. This is useful for generating updated INP files based on version control changes. ```python from swmmio.version_control.inp import BuildInstructions # Assuming 'build_instr' is a BuildInstructions object # 'baseline_dir' is the path to the baseline SWMM model directory # 'target_path' is the desired path for the new INP file build_instr.build(baseline_dir='path/to/baseline/model', target_path='path/to/new/model.inp') ``` -------------------------------- ### find_byte_range_of_section Source: https://swmmio.readthedocs.io/en/latest/reference/utils/text.html Returns the start and end byte locations of substrings within a text file. ```APIDOC ## find_byte_range_of_section ### Description Returns the start and end “byte” location of substrings in a text file. ### Parameters #### Path Parameters - **path** (str) - Required - Path to the text file. - **start_string** (str) - Required - The string to find the byte range for. ``` -------------------------------- ### Instantiate swmmio.Model Source: https://swmmio.readthedocs.io/en/latest/usage/working_with_pyswmm.html Instantiate a swmmio.Model object to interact with a SWMM model. This is useful for accessing model summary information. ```python from IPython.display import HTML import swmmio import pyswmm # path to a SWMM model from swmm-nrtestsuite model_path = 'https://raw.githubusercontent.com/USEPA/swmm-nrtestsuite/refs/heads/dev/public/examples/Example1.inp' model = swmmio.Model(model_path) model.summary ``` -------------------------------- ### Accessing SWMM INP Report Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Demonstrates how to access the report section of a SWMM INP file. This example shows the status of various reporting parameters like INPUT, CONTROLS, and NODES. ```python from swmmio.examples import jersey print(jersey.inp.report) ``` -------------------------------- ### trace_from_node Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/utils/functions.html Traces flow paths (up or down) in a SWMM network starting from a specified node, optionally stopping at another node. ```APIDOC ## trace_from_node ### Description Trace up and down a SWMM model given a start node and optionally a stop node. ### Parameters * **conduits** (pandas.DataFrame) - DataFrame containing conduit information (e.g., InletNode, OutletNode). * **startnode** (string) - The ID of the node from which to start tracing. * **mode** (string, optional) - The direction of the trace. 'up' to trace upstream, 'down' to trace downstream. Default is 'up'. * **stopnode** (string, optional) - The ID of a node at which to stop the trace. If not provided, the trace continues until all reachable nodes are found. ### Returns * **dict** - A dictionary containing two lists: 'nodes' (list of traced node IDs) and 'conduits' (list of traced conduit IDs). ### Examples ```python # Assuming 'conduits_df' is a pandas DataFrame with conduit data # and 'start_node_id' is the ID of the starting node. # traced_path = trace_from_node(conduits_df, start_node_id, mode='down') # print(traced_path) ``` ``` -------------------------------- ### streets Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the streets section of the INP file. Returns a pandas DataFrame. Can be set with a pandas DataFrame. ```APIDOC ## streets ### Description Get or set the streets section of the INP file. Returns a pandas DataFrame. Can be set with a pandas DataFrame. ### Method GET / SET ### Parameters #### Request Body (Setter) - **df** (pandas.DataFrame) - Required - The DataFrame to set as streets data. ### Response (Getter) - **streets_df** (pandas.DataFrame) - The streets data as a DataFrame. ``` -------------------------------- ### Accessing SWMM INP Outlets Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Provides an example of accessing the outlets section of a SWMM INP file. This snippet demonstrates how to retrieve detailed information about a specific outlet, such as 'C11'. ```python from swmmio.examples import streets print(streets.inp.outlets.loc['C11']) ``` -------------------------------- ### tags Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the tags section of the INP file. Returns a pandas DataFrame. Can be set with a pandas DataFrame. ```APIDOC ## tags ### Description Get or set the tags section of the INP file. Returns a pandas DataFrame. Can be set with a pandas DataFrame. ### Method GET / SET ### Parameters #### Request Body (Setter) - **df** (pandas.DataFrame) - Required - The DataFrame to set as tags data. ### Response (Getter) - **_tags_df** (pandas.DataFrame) - The tags data as a DataFrame. ``` -------------------------------- ### Accessing and Modifying INP Options Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Demonstrates how to get and set the options section of an INP file. It shows how changing the infiltration type updates the expected header columns. ```python >>> import swmmio >>> from swmmio.tests.data import MODEL_FULL_FEATURES_XY >>> model = swmmio.Model(MODEL_FULL_FEATURES_XY) >>> model.inp.options.loc['INFILTRATION'] # doctest: +ELLIPSIS Value HORTON Name: INFILTRATION, dtype: ... >>> model.inp.headers['[INFILTRATION]'] ['Subcatchment', 'MaxRate', 'MinRate', 'Decay', 'DryTime', 'MaxInfil'] >>> model.inp.options.loc['INFILTRATION', 'Value'] = 'GREEN_AMPT' >>> model.inp.headers['[INFILTRATION]'] ['Subcatchment', 'Suction', 'HydCon', 'IMDmax', 'Param4', 'Param5'] ``` -------------------------------- ### controls Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the controls section of the SWMM model. Returns a pandas DataFrame of controls. Can be set with a pandas DataFrame. ```APIDOC ## controls ### Description Get or set the controls section of the SWMM model. Returns a pandas DataFrame of controls. Can be set with a pandas DataFrame. ### Method GET / SET ### Parameters #### Request Body (Setter) - **df** (pandas.DataFrame) - Required - The DataFrame to set as controls data. ### Response (Getter) - **_controls_df** (pandas.DataFrame) - The controls data as a DataFrame. ``` -------------------------------- ### Get Dividers DataFrame Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Retrieves the 'Dividers' section of the INP file as a pandas DataFrame. If the DataFrame has not been loaded, it will be loaded from the file. ```python >>> from swmmio.examples import spruce >>> spruce.inp.dividers #doctest: +NORMALIZE_WHITESPACE Elevation Diverted Link Type Parameters Name NODE5 3.0 C6 CUTOFF 1.0 ``` -------------------------------- ### Accessing SWMM INP Patterns Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Illustrates how to access the patterns section of a SWMM INP file. This example shows how to retrieve the first five columns of the patterns dataframe, typically used for time-varying factors. ```python from swmmio.examples import pump_control # NOTE, only the first 5 columns are shown in the following example print(pump_control.inp.patterns.iloc[:,0:5]) ``` -------------------------------- ### Plotting SWMM Network with Recursive Depth (Walnut Model) Source: https://swmmio.readthedocs.io/en/latest/usage/making_art_with_swmm.html Demonstrates plotting a SWMM network using the 'walnut' example model. It includes finding nodes with zero in-degree and recursively plotting paths. ```python from swmmio.examples import walnut walnut = swmmio.Model(walnut.inp.path) # Start the plot as usual ax = walnut.links.geodataframe.plot(color='green', linewidth=walnut.links.geodataframe['Geom1'], capstyle='round', figsize=(20, 10)) # Find nodes with zero in-degree G = walnut.network zero_indegree = [n for n in G.nodes() if G.in_degree(n) == 0] # Run the recursive plotting function with a maximum depth of 3 plot_recursive(walnut, ax, zero_indegree, depth=1, max_depth=3) ax.set_axis_off() ``` -------------------------------- ### Get Outfalls DataFrame Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Retrieves the 'Outfalls' section of the INP file as a pandas DataFrame. If the DataFrame has not been loaded, it will be loaded from the file. ```python >>> model.inp.outfalls #doctest: +NORMALIZE_WHITESPACE InvertElev OutfallType StageOrTimeseries Name J4 0 FREE NO ``` -------------------------------- ### Initialize SWMM Input Object Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Creates an accessible SWMM .inp object. Ensure the INP file has been saved in the GUI before using this. ```python class inp(SWMMIOFile): # creates an accessible SWMM .inp object # make sure INP has been saved in the GUI before using this def __init__(self, file_path): self._options_df = None self._files_df = None self._raingages_df = None self._evaporation_df = None self._losses_df = None self._report_df = None self._conduits_df = None self._xsections_df = None self._lid_usage_df = None self._pollutants_df = None self._landuses_df = None self._buildup_df = None self._washoff_df = None self._coverages_df = None self._loadings_df = None self._pumps_df = None self._orifices_df = None self._weirs_df = None self._junctions_df = None self._outfalls_df = None self._storage_df = None self._dividers_df = None self._coordinates_df = None self._dwf_df = None self._rdii_df = None self._hydrographs_df = None self._vertices_df = None self._polygons_df = None self._subcatchments_df = None self._subareas_df = None self._infiltration_df = None self._aquifers_df = None self._groundwater_df = None self._inp_section_details = None self._inflows_df = None self._curves_df = None self._timeseries_df = None self._tags_df = None self._streets_df = None self._inlets_df = None self._outlets_df = None self._inlet_usage_df = None self._patterns_df = None self._controls_df = None SWMMIOFile.__init__(self, file_path) # run the superclass init self._sections = [ '[OPTIONS]', '[FILES]', '[RAINGAGES]', '[EVAPORATION]', '[LOSSES]', '[REPORT]', '[CONDUITS]', '[XSECTIONS]', '[POLLUTANTS]', '[LANDUSES]', '[BUILDUP]', '[WASHOFF]', '[COVERAGES]', '[LOADINGS]', '[PUMPS]', '[ORIFICES]', '[WEIRS]', '[JUNCTIONS]', '[STORAGE]', '[DIVIDERS]', '[OUTFALLS]', '[VERTICES]', '[SUBCATCHMENTS]', '[SUBAREAS]', '[INFILTRATION]', '[AQUIFERS]', '[GROUNDWATER]', '[CURVES]', '[COORDINATES]', '[DWF]', '[RDII]', '[HYDROGRAPHS]', '[INFLOWS]', '[Polygons]', '[TIMESERIES]', '[LID_USAGE]', '[TAGS]', '[STREETS]', '[INLETS]', '[OUTLETS]', '[INLET_USAGE]', '[PATTERNS]', '[CONTROLS]', ] ``` -------------------------------- ### Access Junctions Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Get the junctions section of the INP file. This section defines the properties of junction nodes in the network. ```python import swmmio from swmmio.tests.data import MODEL_FULL_FEATURES__NET_PATH >>> model = swmmio.Model(MODEL_FULL_FEATURES__NET_PATH) >>> model.inp.junctions InvertElev MaxDepth InitDepth SurchargeDepth PondedArea Name J3 6.547 15 0 0 0 1 17.000 0 0 0 0 2 17.000 0 0 0 0 3 16.500 0 0 0 0 4 16.000 0 0 0 0 5 15.000 0 0 0 0 J2 13.000 15 0 0 0 ``` -------------------------------- ### Instantiate SWMM Model from URL Source: https://swmmio.readthedocs.io/en/latest/usage/visualizing_models.html Instantiates a SWMM model object by passing a URL to the inp file. This is useful for models hosted remotely. ```python import swmmio # url to the inp file hosted on GitHub URL = 'https://raw.githubusercontent.com/SWMMEnablement/1729-SWMM5-Models/dd846c1466c1219019492cc7895f049d298f6d2f/SWMM5_NCIMM/10070_H_Elements.inp' # instatiate a model object by passing in a URL model = swmmio.Model(URL) ``` -------------------------------- ### Access Infiltration Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Get the infiltration section of the INP file. This section defines parameters for soil infiltration models. ```python import swmmio from swmmio.tests.data import MODEL_FULL_FEATURES__NET_PATH >>> m = swmmio.Model(MODEL_FULL_FEATURES__NET_PATH) >>> m.inp.infiltration MaxRate MinRate Decay DryTime MaxInfil Subcatchment S1 3.0 0.5 4 7 0 S2 3.0 0.5 4 7 0 S3 3.0 0.5 4 7 0 S4 3.0 0.5 4 7 0 ``` -------------------------------- ### SWMMIOFile Initialization Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Initializes a SWMMIOFile object, which serves as a base class for handling SWMM report files (.rpt). It stores file path, name, directory, and size. ```python from swmmio.tests.data import RPT_FULL_FEATURES report = rpt(RPT_FULL_FEATURES) ``` -------------------------------- ### Access Dividers Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Get the dividers section of the INP file. This section defines flow diversion points in the model. ```python from swmmio.examples import spruce >>> spruce.inp.dividers Elevation Diverted Link Type Parameters Name NODE5 3.0 C6 CUTOFF 1.0 ``` -------------------------------- ### Instantiate and Access Node Data Source: https://swmmio.readthedocs.io/en/latest/reference/elements.html Shows how to create a Nodes object for SWMM nodes, specifying input and report sections, and selecting specific columns. It then displays the resulting data as a Pandas DataFrame. ```python from swmmio.examples import spruce nodes = Nodes( spruce, inp_sections=['junctions'], rpt_sections=['Node Depth Summary'], columns=['InvertElev', 'MaxHGL', 'coords'] ) print(nodes.dataframe) ``` -------------------------------- ### Get Link Coordinates Source: https://swmmio.readthedocs.io/en/latest/reference/utils/dataframes.html Helper function designed for use with `df.apply` to retrieve coordinates for conduits or links within a DataFrame. ```python swmmio.utils.dataframes.get_link_coords(_row_ , _nodexys_ , _verticies_) ``` -------------------------------- ### patterns Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the patterns section of the SWMM model. Returns a pandas DataFrame representing the patterns. Can be set with a pandas DataFrame. ```APIDOC ## patterns ### Description Get or set the patterns section of the SWMM model. Returns a pandas DataFrame representing the patterns. Can be set with a pandas DataFrame. ### Method GET / SET ### Parameters #### Request Body (Setter) - **df** (pandas.DataFrame) - Required - The DataFrame to set as patterns data. ### Response (Getter) - **_patterns_df** (pandas.DataFrame) - The patterns data as a DataFrame. ``` -------------------------------- ### Utility Functions for Text File I/O Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/utils/text.html This section introduces utility functions designed for I/O operations with text files within the swmmio library. ```python # UTILITY FUNCTIONS AIMED AT I/O OPERATIONS WITH TEXT FILES ``` -------------------------------- ### Accessing Buildup Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Shows how to access and query the buildup section of an INP file, specifically filtering for 'Pollutant', 'Function', and 'Normalizer' columns. ```python >>> from swmmio.examples import walnut >>> walnut.inp.buildup[['Pollutant', 'Function', 'Normalizer']] Pollutant Function Normalizer LandUse Residential Lead NONE AREA Residential TSS SAT AREA Undeveloped Lead NONE AREA Undeveloped TSS SAT AREA ``` -------------------------------- ### Get Tags DataFrame Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Retrieves the tags section of the SWMM input file as a pandas DataFrame. If the DataFrame is already loaded, it is returned. ```python if self._tags_df is None: self._tags_df = dataframe_from_inp(self.path, "[TAGS]") return self._tags_df ``` -------------------------------- ### inp.aquifers Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the 'Aquifers' section of the INP file as a pandas DataFrame. This property allows for the retrieval and modification of aquifer properties. ```APIDOC ## inp.aquifers ### Description Get or set the 'Aquifers' section of the INP file as a pandas DataFrame. This property allows for the retrieval and modification of aquifer properties. ### Method GET/SET ### Endpoint N/A (Object Property) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **df** (pandas.DataFrame) - Required - The DataFrame to set for the aquifers section. ### Request Example ```python # Get aquifers aquifers_df = model.inp.aquifers # Set aquifers new_aquifers_df = pd.DataFrame(...) model.inp.aquifers = new_aquifers_df ``` ### Response #### Success Response (200) - **pandas.DataFrame**: A DataFrame representing the 'Aquifers' section of the INP file. ``` -------------------------------- ### Basic Network Visualization Source: https://swmmio.readthedocs.io/en/latest/usage/visualizing_models.html Generates a quick visualization of the sewer network using swmmio's draw_model function. Useful for a rapid overview. ```python swmmio.draw_model(model, title='NCIMM Black and White Box Model') ``` -------------------------------- ### inp.subareas Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the 'Subareas' section of the INP file as a pandas DataFrame. This property allows for the retrieval and modification of subarea data. ```APIDOC ## inp.subareas ### Description Get or set the 'Subareas' section of the INP file as a pandas DataFrame. This property allows for the retrieval and modification of subarea data. ### Method GET/SET ### Endpoint N/A (Object Property) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **df** (pandas.DataFrame) - Required - The DataFrame to set for the subareas section. ### Request Example ```python # Get subareas subareas_df = model.inp.subareas # Set subareas new_subareas_df = pd.DataFrame(...) model.inp.subareas = new_subareas_df ``` ### Response #### Success Response (200) - **pandas.DataFrame**: A DataFrame representing the 'Subareas' section of the INP file. ``` -------------------------------- ### Combine BuildInstructions Objects Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/version_control/inp.html Merges two BuildInstructions objects into a new one. It combines instructions for common sections and includes unique sections from both objects. Metadata is also merged. ```python from swmmio.version_control.inp import BuildInstructions # Assuming bi1 and bi2 are existing BuildInstructions objects combined_bi = bi1 + bi2 # Or using sum() on a list of BuildInstructions objects # build_instructions_list = [bi1, bi2, bi3] # combined_bi = sum(build_instructions_list) ``` -------------------------------- ### inp.subcatchments Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the 'Subcatchments' section of the INP file as a pandas DataFrame. This property enables reading and writing subcatchment data. ```APIDOC ## inp.subcatchments ### Description Get or set the 'Subcatchments' section of the INP file as a pandas DataFrame. This property enables reading and writing subcatchment data. ### Method GET/SET ### Endpoint N/A (Object Property) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **df** (pandas.DataFrame) - Required - The DataFrame to set for the subcatchments section. ### Request Example ```python # Get subcatchments subcatchments_df = model.inp.subcatchments # Set subcatchments new_subcatchments_df = pd.DataFrame(...) model.inp.subcatchments = new_subcatchments_df ``` ### Response #### Success Response (200) - **pandas.DataFrame**: A DataFrame representing the 'Subcatchments' section of the INP file. ``` -------------------------------- ### outfalls Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the 'outfalls' section of the INP file as a pandas DataFrame. This property provides access to outfall node configurations. ```APIDOC ## outfalls ### Description Get or set the 'outfalls' section of the INP file as a pandas DataFrame. This property provides access to outfall node configurations. ### Method GET/SET ### Endpoint `inp.outfalls` ### Parameters #### Request Body - **df** (pandas.DataFrame) - Required - The DataFrame to set as the outfalls section. ### Response #### Success Response (200) - **pandas.DataFrame** - The outfalls section of the INP file. ### Request Example ```python import swmmio from swmmio.tests.data import MODEL_FULL_FEATURES__NET_PATH model = swmmio.Model(MODEL_FULL_FEATURES__NET_PATH) # outfalls_data = model.inp.outfalls # Set outfalls data (example with modified data) # model.inp.outfalls = new_outfalls_df ``` ### Response Example ```python # Example of returned DataFrame structure: # (Structure depends on the specific outfall definitions in the INP file) ``` ``` -------------------------------- ### ModelSection Base Class Initialization Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/elements.html Initializes the base class for model elements, setting up references to the SWMM model, input/report file paths, and configuration for data joining and geometry type. ```python class ModelSection(object): """ Base class of a group of model elements. :param model: swmmio.Model object :param inp_sections: list of node-related sections from the inp file to concatenate in the object :param join_sections: list of node-related sections from the inp file to join to the object :param rpt_sections: list of node-related sections from the rpt file to join to the object :param columns: optional subset of columns used to exclude unwanted columns in the resulting object :param geomtype: type of geometry for section [point, linestring, polygon] """ def __init__(self, model, inp_sections, join_sections=None, rpt_sections=None, columns=None, geomtype='point'): self.model = model self.inp = self.model.inp self.rpt = self.model.rpt self.inp_sections = inp_sections self.join_sections = join_sections if join_sections is not None else [] self.rpt_sections = rpt_sections if rpt_sections is not None else [] self.columns = columns self.geomtype = geomtype self._df = None ``` -------------------------------- ### weirs Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the '[WEIRS]' section of the INP file as a pandas DataFrame. This property provides access to weir structure configurations. ```APIDOC ## weirs ### Description Get or set the '[WEIRS]' section of the INP file as a pandas DataFrame. This property provides access to weir structure configurations. ### Method GET/SET ### Endpoint `inp.weirs` ### Parameters #### Request Body - **df** (pandas.DataFrame) - Required - The DataFrame to set as the weirs section. ### Response #### Success Response (200) - **pandas.DataFrame** - The weirs section of the INP file. ### Request Example ```python # Assuming 'model' is an instance of swmmio.Model # weirs_data = model.inp.weirs # Set weirs data (example with modified data) # model.inp.weirs = new_weirs_df ``` ### Response Example ```python # Example of returned DataFrame structure: # (Structure depends on the specific weir definitions in the INP file) ``` ``` -------------------------------- ### Accessing Controls Section Source: https://swmmio.readthedocs.io/en/latest/reference/swmmio_inp.html Illustrates how to access the controls section of an INP file, displaying the defined pump control rules. ```python >>> from swmmio.examples import pump_control >>> pump_control.inp.controls Control Name RULE PUMP1A IF NODE SU1 DEPTH >= 4 THEN PUMP PUMP1 status = ON PRIORITY 1 RULE PUMP1B IF NODE SU1 DEPTH < 1 THEN PUMP PUMP1 status = OFF PRIORITY 1 ``` -------------------------------- ### pumps Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/core.html Get or set the '[PUMPS]' section of the INP file as a pandas DataFrame. This property provides access to pump station configurations. ```APIDOC ## pumps ### Description Get or set the '[PUMPS]' section of the INP file as a pandas DataFrame. This property provides access to pump station configurations. ### Method GET/SET ### Endpoint `inp.pumps` ### Parameters #### Request Body - **df** (pandas.DataFrame) - Required - The DataFrame to set as the pumps section. ### Response #### Success Response (200) - **pandas.DataFrame** - The pumps section of the INP file. ### Request Example ```python # Assuming 'model' is an instance of swmmio.Model # pumps_data = model.inp.pumps # Set pumps data (example with modified data) # model.inp.pumps = new_pumps_df ``` ### Response Example ```python # Example of returned DataFrame structure: # (Structure depends on the specific pump definitions in the INP file) ``` ``` -------------------------------- ### Save BuildInstructions to File Source: https://swmmio.readthedocs.io/en/latest/_modules/swmmio/version_control/inp.html Saves the current BuildInstructions object to a specified directory and filename. It writes metadata and the changes (removed, altered, added) for each section to the file. ```python from swmmio.version_control.inp import BuildInstructions # Assuming 'build_instr' is a BuildInstructions object # Save to a directory named 'output' with filename 'instructions.txt' build_instr.save(dir='output', filename='instructions.txt') ``` -------------------------------- ### Running Multiple SWMM Models in Parallel Source: https://swmmio.readthedocs.io/en/latest/usage/getting_started.html Start a pool of simulations to run multiple SWMM models concurrently using multiprocessing. Specify directories containing SWMM .inp files. ```bash # run all models in models in directories Model_Dir1 Model_Dir2 python -m swmmio -sp Model_Dir1 Model_Dir2 # leave 1 core unused python -m swmmio -sp Model_Dir1 Model_Dir2 -cores_left=1 ```