Proposed feature - model summary stats and warnings

[aerispaha]

Provide an interface to easily retrieve macro summary stats about a EPA SWMM model. Included in the summary stats could be things like:

• total # of links
• total # of junctions
• total # of other model elements
• invert elevation range (min elevation, max elevation)
• Largest, smallest conduits
• total length of conduits
• total # of nodes with inflows, flow patterns, etc

Also provide a warnings about the model configuration. For example:

• connectivity issues
  • stranded nodes not connected to anything
  • isolated subsheds
  • links with undefined nodes
  • links without XSECTIONS
• adverse slopes

I'm not sure how best to design the API for this feature. Here is an idea:

model = swmmio.Model('path-to-model.inp')

model.summary

[everettsp]

Nice idea, had a quick go at a summary:

Created the following in functions.py:

def summarize_model(model):
    model_summary = dict()

    # numbers of elements
    model_summary['num_subcatchments'] = len(model.inp.subcatchments)
    model_summary['num_conduits'] = len(model.inp.conduits)
    model_summary['num_junctions'] = len(model.inp.juntions)
    model_summary['num_outfalls'] = len(model.inp.outfalls)
    model_summary['num_raingages'] = len(model.inp.raingages)

    # calculated values - only calculate if elements exist
    if len(model.inp.subcatchments) != 0:
        model_summary['catchment_area'] = model.inp.subcatchments.Area.sum()
        model_summary['mean_subcatchment_slope'] = ((model.inp.subcatchments.Area / model.inp.subcatchments.Area.sum()) * model.inp.subcatchments.PercSlope).sum()
    
    if len(model.inp.conduits) != 0:
        model_summary['total_conduit_length'] = model.inp.conduits.Length.sum()
    
    if len(model.nodes) != 0:
        model_summary['invert_range'] = model.nodes().InvertElev.max() - model.nodes().InvertElev.min()
    return model_summary

and the following model property in core.py:

    @property
    def summary(self):
        if self._summary is None:
            model_summary = functions.summarize_model(self)
            self._summary = model_summary
        return self._summary

I thought for warnings it would be easiest to simply grab them from the .rpt file with the following Model function:

    def rpt_warnings(self, verbose=False):
        """
        Return warning messages from the rpt file
        """
        # first, make sure the rpt is valid
        if self.rpt_is_valid(verbose=verbose):
            # check if the rpt has ERRORS output from SWMM
            warnings = list()
            with open(self.rpt.path) as f:
                for line in f:
                    spl = line.split()
                    if len(spl) > 0 and spl[0] == 'WARNING':
                        warnings.append(line[:-1])
                    elif '****************' in line:
                        break
                return warnings

That said, there might be useful warnings that aren't generated in the .rpt file. Let me know what you think and if you'd like for me to throw together a PR.

[aerispaha]

@everettsp I love this! Thank you for taking the lead on this new feature. Please do create a PR and we can work on integrating this in a future release. I figure we can start relatively simple and then add more things to the summary as we think of them.

@bemcdonnell, any other thoughts or objections?

[bemcdonnell]

@aerispaha All that information is helpful! if we can start to categorize the warnings, we could consider making auto-remedies to the problems. @everettsp Looking forward to working with you!