swmmio

https://swmmio.readthedocs.io/en/latest/
Admin
swmmio is a Python tool designed for engineers and hydrologists to programmatically pre and...
Tokens:102,571
Snippets:802
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### 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
```
Tokens:
Raw