Reorg Project: PROPOSAL

[bemcdonnell]

I have been thinking about how this project is used (or how it could be used in the future). I think we have good coverage on the INP [READ/EXTRACT/EDIT/SAVE] functionalities. Furthermore, this project also does a good job with RPT [READ]. There are also GIS features that are super powerful and finally, mapping and profile plotting are useful feature sets. I like the default runner process onboard (especially since it is now x-platform compatible having onboarded pyswmm).

If I were a potential user stumbling onto swmmio, I might feel a little bit lost. The documentation does not provide clear guidance on all the use-cases covered by this project. Furthermore, if I were a developer off the street, I might not know how best my code/ideas could fit into the project.

Dreaming up a possible future, I think the code and tools should be organized much like how a user might put it into their workflow. The following figure demonstrates some workflow options. "Square" boxes are normal starting points.

graph LR;
    A[Open MODEL]-->B;
    B(Edit/Save MODEL)-->H;
    B-->G
    A-->G(Network Analysis *Tools*);   
    H(Export to GIS *Tools*);
    
    D(Run Model - optional)-->E;
    E[Open Model/RPT/OUT]-->F(Graphic/Table *Tools*);

    G-->F;

What you see is that the typical user might want to open->edit->save a model. Then, open->interpret->graph results. The workflows would then expose the following features groups to the users.

• [MODEL] Manipulate Model (OPEN/EDIT/SAVE)
• [RESULTS] Interpret Results (RPT/OUT)
• [TOOLS] ...
  1. Run (optional, but available)
  2. Graph (Network Map, Profile, Timeseries?)
  3. Network Analysis (connectivity, select)
  4. GIS features (to Geopackage)
  5. Something I haven't thought of

[bemcdonnell]

@aerispaha I'm hoping to make a YouTube video soon on the profiler aspect that was added a few weeks ago. Before I do that, I am hoping we can make some modifications to the documentation so that we need not re-record the video. Do you have a few minutes to review this and then we can spend time to build out the docs? Just trying to keep the docs in a row :duck::duck::duck:

[aerispaha]

@bemcdonnell I think this reorg proposal is solid!

Overall I think it makes sense to organize the documentation (and the code) into these three general areas: model i/o and manipulation, results interpretation/exploration, and tools, which I think is totally in line with your proposal. I also agree that the "tools" scope can include a collection of higher level algorithms that help facilitate common modeling tasks.

I'm on board!

Maybe as a next step we can outline a few common modeling workflows within which swmmio could be a super useful. Ten we can start to taylor the docs to focus on these workflows. What do you think?