A bioretention scenario produces less runoff than the existing drainage model. That looks promising, but what happens downstream? Peak flow may decrease, critical nodes may flood less, or the intervention may mainly delay water entering the network. Comparing scenarios means establishing which changes occurred and why.

EPA SWMM provides the simulation results. Codex can help inspect input differences, prepare scripts to read saved outputs, and organize the findings into comparison tables and hydrographs. You define the evaluation criteria and review the engineering interpretation.

On Vagon Cloud Computer, SWMM, Codex, Python, and the scenario files work together in one Windows desktop environment. You can inspect models, analyze results, verify findings in SWMM, and prepare the comparison report from the same workspace, with processing handled remotely rather than by your local computer.

This guide compares an existing-condition model with a bioretention scenario. It follows the evidence from input differences to runoff, downstream performance, and the LID water balance, without reducing the decision to a single improvement percentage.

Source: US EPA

Decide What “Better” Means for Each Scenario

A useful comparison starts with project objectives, not whichever result shows the largest reduction. Bioretention may reduce runoff leaving a treated subcatchment while changing the timing of discharge into the drainage network. Those effects need separate evaluation.

For this walkthrough, organize the analysis around four questions:

Select the review locations before examining scenario differences. Include the treated subcatchment, its receiving drainage connection, and downstream locations relevant to the project. This keeps the analysis from highlighting a local benefit while overlooking a problem elsewhere.

Give Codex a focused assignment:

Define the deliverables at this stage: an input-change record, a comparison scorecard, selected hydrographs, and unresolved findings.

A lower peak or smaller runoff volume is a calculated result. Whether that change satisfies drainage requirements is a separate judgment based on approved criteria, not a conclusion Codex should supply on its own.

Set Up SWMM and Codex on Vagon Cloud Computer

Use Vagon Cloud Computer as the complete working environment for the comparison: open the models in SWMM, run analysis scripts with Codex, inspect charts, and prepare the report without moving files between machines.

1. Select your applications

During computer creation, use application selection to choose EPA SWMM, Codex, and Python.

Once the desktop is ready, open SWMM and record its version. Sign in to Codex and open the comparison project folder. Confirm that the agent can access the intended files before asking it to execute analysis commands.

2. Create the analysis environment

Open a terminal in the project directory and create a dedicated Python environment:

python -m venv .venv
.\.

python -m venv .venv
.\.

PySWMM’s Output module provides access to saved binary results. pandas organizes time series and comparison tables, while matplotlib generates figures.

Ask Codex to use this environment’s interpreter and record package versions. This post-processing setup does not require rerunning either model.

3. Transfer both scenarios and their dependencies

Use Vagon Files to transfer the baseline and bioretention scenarios. Include .inp, .rpt, and .out files, plus referenced rainfall and other external data.

Preserve relative folder paths and keep generated analysis separate:

Open both input models in SWMM to confirm they are readable, without saving changes or launching simulations. Result-file provenance will be checked next.

Set a clear boundary for Codex: read the scenario folders, write to the analysis folders, and request approval before modifying inputs or running simulations. Use protected source copies or filesystem permissions when that boundary needs technical enforcement.

Prove That the Scenarios Differ for the Intended Reason

Before comparing runoff or flooding, establish what changed between the models. A scenario named “Bioretention” may also contain revised rainfall, altered pipe dimensions, or different simulation settings. Without an input review, those changes can be mistaken for LID benefits.

Ask Codex to compare the .inp files by section and object ID, not just by line number. Reordered records or comments should not be treated as hydraulic changes.

Check the conditions that frame the comparison

Review these groups before accepting the scenarios as comparable:

Matching filenames are insufficient for external data. Compare the referenced contents or record file hashes so two different rainfall files with the same name do not pass unnoticed.

Source: US EPA

Review LID deployment, not just its name

For the bioretention scenario, inspect both the control definition and its deployment within each subcatchment. Confirm the number of units, area per unit, treated drainage area, initial saturation, and destinations for surface and underdrain discharge.

Source: US EPA

Related subcatchment changes may be necessary to represent the design correctly. Do not require every non-LID field to remain identical without review.

Finish with an approved change list. If the scenario also includes a larger downstream pipe, either retain that as an explicitly combined intervention or prepare a separate comparison. Codex should expose the distinction, not attribute the combined result to bioretention alone.

Source: US EPA

Match Each Input to a Complete, Reviewable Run

An input comparison establishes the intended model differences. Next, confirm that the saved results were actually produced from those inputs.

Keep a scenario manifest linking each .inp file to its .rpt and .out files. Record the scenario ID, available run timestamps, solver version, simulation period, and file hashes. A hash identifies a file; it does not prove that an existing output was generated from it unless that relationship was recorded when the model ran.

Check completion and numerical behavior

The SWMM User’s Manual distinguishes the text report from the binary results. Review both: an .out file’s existence alone does not establish that the requested simulation completed successfully.

Ask Codex to prepare a run-check table:

Continuity checks describe numerical water accounting, not design performance. A small error does not establish calibration or correct inputs. Conversely, a warning needs investigation in context rather than an automatic rejection of every result.

Source: US EPA

Also confirm which objects were saved and when reporting began. Missing results are not zero values, and an output period shorter than the analysis period may exclude relevant behavior.

Resolve uncertain provenance before proceeding

If the input-to-output relationship cannot be established, label it unconfirmed. Request approval to rerun the preserved inputs using a documented solver version and new output locations. Record the run command and completion status, and retain the original files.

That creates a defensible starting point for extracting scenario metrics.

Extract a Small Set of Decision-Relevant Results

Start with the review locations chosen in the comparison brief. Extracting every variable from every object creates more data, but not necessarily a clearer decision.

Build a result-selection table first:

Use PySWMM’s Output module to read saved .out files. This is separate from its simulation interface: opening a completed output does not run the model.

Extract one verified series first

The following example reads flow at one link from both scenarios and saves their recorded values:

The LinkSeries interface returns values indexed by reporting timestamps. This example preserves each scenario separately; it does not align timestamps, convert units, or calculate differences. Exclusive file creation prevents accidental overwriting.

Keep values attached to their definitions

For each extracted table, record the source file, object ID, variable, units, period, and extraction script version. Read and verify units rather than assigning them from an example.

Check several values against the same object and timestamps in SWMM. Confirm that node head, node depth, and flooding rate have not been confused.

Source: US EPA

Use report summaries alongside the time series. A peak calculated from saved reporting samples can differ from a solver-reported peak, and integrating those samples produces an estimate of volume rather than automatically reproducing the report total.

Source: US EPA

Also distinguish water stored within a link from cumulative water transported through it. A variable called flow_volume should not be treated as integrated discharge merely because its name includes “flow.” Resolve definitions before adding any metric to the scorecard.

Build a Scorecard That Shows Trade-Offs

Bring the verified results into one comparison table, with a separate row for each metric and review location. Avoid combining everything into an overall performance score unless the project has an approved weighting method.

Use this structure:

Define the direction of every calculation. For a reduction metric:

A positive result indicates a reduction, not automatically an engineering benefit. If the baseline is zero, report the absolute change and mark percentage reduction as undefined.

Keep local and downstream effects separate

Do not add runoff volumes across subcatchments without checking their connections. Water leaving one subcatchment may enter another, so an indiscriminate total can count routed water more than once.

Source: US EPA

Likewise, a reduction in the treated subcatchment’s peak does not establish the same reduction at the outfall. Examine the selected downstream hydrograph, including whether the shifted discharge coincides with other contributions.

Source: US EPA

For flow-volume calculations, document the integration method, time units, and treatment of reverse flow. Net transported volume and total movement in both directions answer different questions.

Make unfavorable results visible

Ask Codex to preserve the full comparison:

Plot both scenarios on shared axes and retain missing observations. If one location improves while another deteriorates, report that trade-off explicitly. The scorecard should explain the evidence, not manufacture a single winning scenario.

Follow the Water Through the LID Scenario

A smaller runoff hydrograph does not explain how bioretention changed the water balance. Some incoming water may infiltrate, some may evaporate, some may remain stored, and some may leave through surface overflow or an underdrain.

Use SWMM’s LID performance reporting to examine those pathways together:

Underdrain discharge is not automatically water removed from the drainage network. Check its destination and compare its timing with the receiving network’s response.

Convert reported quantities carefully

The LID summary expresses water-balance quantities as depths over the LID surface area. Before converting them to volumes, confirm the relevant deployment area, number of units, and reporting scope.

For depth in millimeters and area in square meters:

Do not use the entire subcatchment area or multiply by unit count twice. Preserve the original reported values alongside conversions.

Distinguish retention from delay

If the scenario ends with substantial stored water, the comparison may capture delayed release rather than permanent runoff reduction. Review whether the simulation includes enough drain-down time for the intended assessment.

Ask Codex to flag incomplete accounting, not fill the gap with an assumed benefit. If a longer simulation is needed, request approval and apply a consistent analysis period to both scenarios. Report the modeled pathways without adding LID totals to runoff or network totals that may already include the same water.

Check the Comparison in SWMM and Write the Findings

Before drafting conclusions, open the selected results in SWMM and check the values behind the scorecard. Use the Status and Summary reports, time-series tables, and relevant profile plots.

Source: US EPA

Verify a few representative findings, including the largest improvement, any adverse change, and results affected by numerical warnings.

Keep surcharge and flooding separate. A surcharged conduit or elevated hydraulic head does not automatically mean water has left the system. Ponding settings also affect whether excess water is stored at the surface for possible re-entry or treated as lost.

SWMM node flooding results are not, by themselves, a map of surface flood extent or inundation depth. Do not turn a reduction in reported flooding volume into a claim about specific properties protected without supporting analysis.

Write a source-linked findings summary

Ask Codex to draft the report from the reviewed outputs:

Keep this report, the extraction scripts, charts, and input-change record together on Vagon Cloud Computer. Review scenario names, calculation signs, units, and source references before sharing the package. Another reviewer should be able to reproduce the comparison without relying on Codex’s explanation alone.

Final Thoughts

A useful SWMM comparison explains more than which scenario produces less runoff. It shows what changed in the inputs, how the drainage network responded, where the LID routed water, and which findings still require review.

Codex can make that work repeatable through extraction scripts, consistent calculations, and source-linked reports. You remain responsible for the modeling assumptions and engineering interpretation.

Vagon Cloud Computer keeps SWMM, Codex, Python, and the scenario files together. Start with a verified comparison, inspect the findings in SWMM, and retain the complete analysis package for future revisions.

FAQs

Can Codex compare SWMM scenarios without MCP?

Yes. Codex can help inspect input files and prepare Python scripts that read saved results. This file-based workflow does not require MCP or direct control of the SWMM interface.

Do I need to rerun both scenarios?

Not if the existing results are complete and reliably linked to the intended inputs. If that relationship is uncertain, a documented rerun may be necessary. Obtain approval and preserve the original files.

Can PySWMM read existing .out files?

Yes. Its Output module reads saved binary results without starting a simulation. Confirm the available objects, variables, units, and reporting timestamps before extracting values.

Why do hydrograph peaks differ from report summaries?

Saved time series use reporting intervals, while summary statistics can reflect calculations between those samples. A sampled hydrograph can therefore miss a higher computed peak.

Does lower runoff guarantee less flooding?

No. Network capacity, discharge timing, underdrain routing, and other inflows affect downstream behavior. Check the relevant nodes and links separately.

Can node flooding results show flood extent?

Not on their own. Flooding rates or volumes do not establish where surface water travels or how deep it becomes across surrounding land.

Can Codex approve the best drainage design?

No. It can organize evidence and calculate agreed metrics, but qualified reviewers must assess design suitability and compliance with project requirements.