Tuesday, October 25, 2022

Combining Ruby with ICM SWMM Network


ICM InfoWorks by Autodesk Innovyze is a complicated program with many parts and a state-of-the-art 1D and 2D engine. One way to deal with the complexity is to automate complicated or repetitive tasks with SQL and Ruby. In this blog, we will use SQL and Ruby to automate the process of assigning Watershed outlet nodes for ICM SWMM Networks.

What are we hoping to achieve by Combining Ruby with ICM SWMM Networks?

  1. We want to find the outlet ID for the closest node to a Subcatchment in an ICM SWMM Network.
  2. Ruby will use the Geometry tools of ICM to find the closest node.
  3. What is an ICM SWMM Network? It is a Network in ICM that uses SWMM 5.1.015 data and most/many of the tools of the ICM GUI. ICM of course also has InfoWorks Networks.
  4. What am I showing in the Post header image? Autodesk has Subscription versions of ICM (Standard and Ultimate), but I am showing the Thales versions of ICM which are both 32bit and 64bit, and comingled ICM InfoWorks and ICM SWMM Networks. I also use InfoWater Pro (Arc GIS Pro) and InfoSWMM which uses Arc Map and has a direct import into an ICM SWMM Network.

ICM SWMM Network Data in the Autodesk Innvovyze ICM GUI
ICM SWMM Network Subcatchment Data

Why use Ruby for InfoWorks ICM SWMM Networks?

Why Ruby - it is part of ICM and easy to understand with a lot of Modeling features. It is part of Network Menu Commands. You can use a new Script or a past used script so it is easy to find.
No alt text provided for this image

What is an InfoWorks ICM SWMM Network?

ICM SWMM uses the SWMM 5.1.015 engine and has most of the UX features of ICM InfoWorks Networks including 2D. A different 1D network and solution of course.

What is an example of Ruby Scripts?

net=WSApplication.current_network
puts 'Running ruby for SWMM Networks'
nodes=Array.new
net.row_object_collection('sw_node').each do |n|
        if n.selected?
                temp=Array.new
                temp << n.id
                temp << n.x
                temp << n.y
                nodes << temp
        end
end
net.transaction_begin
net.row_object_collection('sw_subcatchment').each do |s|
        if s.selected?
                sx = s.x
                sy = s.y
                nearest_distance = 999999999.9
                (0...nodes.size).each do |i|
                        nx = nodes[i][1]
                        ny = nodes[i][2]
                        n_id = nodes[i][0]
                        distance=((sx-nx)*(sx-nx))+((sy-ny)*(sy-ny))
                        if distance < nearest_distance
                                nearest_distance=distance
                                s.outlet_id = n_id
                        end
                end
        else
        puts 'You forgot to select anything'
        end
        s.write
end
puts 'Ending ruby'
net.transaction_commit

Where can I find the Ruby Scripts?

Innovyze has a Github that you can use to copy or download dozens of Ruby and SQL scripts. If registered on our Portal, you can find Salesforce Knowledge Base articles and many other sources of help. at https://github.com/innovyze/Open-Source-Support. SQL and Ruby functionality exist to be used by users with knowledge of programming languages. We provide resources to assist customers in building their scripts through the existing self-help frameworks, including documentation on Ruby, help files, and more recently a wealth of GitHub examples - link above.

How do I use Ruby Scripts?

Easy - Go to the Network Menu and choose Run Ruby Scripts or Recent Ruby Scripts
No alt text provided for this image

Do I need to use SQL?

It helps if you have a simple global grid command and you do not want to edit the grid. Here is a simple SQL that sets the SWMM Network OUTLET_ID to blank. You can save the SQL on the project explorer window and click to activate the dialog.

No alt text provided for this image

What does each line of the Ruby Script represent and what does it perform for the ICM SWMM Network?

The annotated snippet below shows the steps used in the script. ICM SWMM Networks are sw_ whereas ICM InfoWorks Networks are hw_ (for reference)

net=WSApplication.current_network

# Opens the current network on the ICM Geoplan

puts 'Running ruby for SWMM Networks'

# Tell the user some actions are being done by the script

nodes=Array.new

# Makes a new array - uses swmm nodes or sw_node

net.row_object_collection('sw_node').each do |n|
        if n.selected?
                temp=Array.new
                temp << n.id
                temp << n.x
                temp << n.y
                nodes << temp
        end
end
# Save the id, x coordinate, y coordinate to the nodes array of SELECTED Elements

net.transaction_begin

# start finding the nodes to set to the outlet of the subcatchment

net.row_object_collection('sw_subcatchment').each do |s|

# use swmm subcatchments or sw_subcatchment

        if s.selected?

# use the SELECTED Elements

                sx = s.x
                sy = s.y

# use the centroid of the subcatchment

                nearest_distance = 999999999.9
                (0...nodes.size).each do |i|
                        nx = nodes[i][1]
                        ny = nodes[i][2]
                        n_id = nodes[i][0]

# for each node find the x and y coordinates

                        distance=((sx-nx)*(sx-nx))+((sy-ny)*(sy-ny))

# compute the node to subcatchment distance
 
                       if distance < nearest_distance
                                nearest_distance=distance
                                s.outlet_id = n_id

# We have found the closed node and set the outlet ID to the node ID
                        end
                end
        else
        puts 'You forgot to select anything'

# message to remind ourself we forget to select any nodes or subcatchments

        end
        s.write
end
puts 'Ending ruby'
# Tell the user some actions were by the script

net.transaction_commit

# commit our new found ID to the current network (ICM SWMM Network)

I'm attaching a YouTube video that explains the previous stages. It is for ICM SWMM Networks, which utilizes SQL to remove or set the SWMM Subcatchment's OUTLET ID to Null and Ruby to determine the closest node to the Subcatchment's centroid and assign it as the OUTLET ID. I made a mistake and ran Ruby without using ICM to pick any items, which resulted in nothing being done, but at least I received a notice about not choosing any components.





InfoSewer Run Manager and Video showing the Accuracy Parameter

 Innovyze InfoSewer Run Manager

  • Flow Unit - Units of flow measurement (cfs, gpm, mgd, imgd, afd, L/s, L/m, MLd, m3/h, and m3/d).

  • Default Diurnal Pattern - Determines which diurnal pattern will be applied to an EPS simulation when a unique pattern has not been assigned to an individual manhole(s).

  • Global Loading Multiplier - Used to assign a multiplier in which global loadings are to be multiplied.  For example, a MAXDAY EPS model scenario may have a global loading multiplier of 2.5.

  • Accuracy -  Convergence criterion used to signal that a solution has been found to the nonlinear equations that govern network hydraulics.  Trials end when the relative change in pipe flow rates between two successive iterations is less than this number.  The suggested value is 0.001.

  • Diurnal Pattern Usage - Select whether the pattern will linearly interpolate intermediate values (continuous) or evaluate patterns in a stepwise fashion. Click here to learn more about pattern representation options.

  • Default Manhole Sealing Method - Use this to specify the default Manhole cover type for Normal Manholes. Choose Locked to contain flow inside the manhole structure when the water level rises above the rim elevation and choose Unlocked if flow is not contained inside the structure and spills over when the water level rises above the rim elevation. The maximum head possible in the second case is thus the manhole rim elevation

  • Maximum number of segments - The maximum number of segments specifies the maximum number of segments a pipe can be divided into during a flow routing and quality analyses. The default value is 100 segments per pipe. The maximum number of segments affects the speed and accuracy of the hydraulic analysis. The smaller the value the faster the computational speed.

  • Minimum Travel Distance - Minimum Travel Distance is the smallest length that a pipe segment could assume. Pipes shorter than this value will have only one segment. The default value is 100 ft.

  • Minimum Travel Time - Minimum Travel Time establishes the smallest time of travel through a pipe recognized by InfoSewer Travel times smaller than this number are set equal to it (travel times through pumps are instantaneous and are not affected by this limit). The default minimum travel time is 1 second.InfoSewer determines the travel time based on pipe and flow properties, and uses this computed time step for hydraulic calculations during an EPS. The user can assign a desired minimum travel time, and this value is used when calculated travel times are less than the minimum travel time. The maximum allowable value for the minimum travel time is equal to the smaller value of report time step and pattern time step. The minimum travel time affects the speed and accuracy of the water quality analysis (i.e. time of concentration and source tracing). The larger this value is the faster the computational speed.

  • Pumped Flow Conservation - Check this option to set the gravity main flow downstream of a pump equal to  the pump flow thereby forcing it to be an unpeakable load.  If this option is not checked then the gravity main flow downstream of a pump is set equal to the flow entering the wet well. This option can be used only  for steady-state analysis and design.

  • Flow Attenuation - Check this option to include flow/hydrograph attenuation in the EPS simulation. If this option is not checked then flow attenuation will not be considered in the analysis. Flow attenuation in a sewer collection system is the process of reducing the peak flow rate by redistributing the same volume of flow over a longer period of time as a result of friction (resistance), internal storage and diffusion along the sewer pipes.InfoSewer uses a distributed Muskingum-Cunge flow routing method based on diffusion analogy, which is capable of accurately predicting hydrograph attenuation or peak flow damping effects (peak subsidence). This option can only be used for extended period simulation.

  • Unit Hydrograph Adjustment Threshold(%) - The option provides the flexibility whether to adjust ordinates of synthetic unit hydrograph such as Tri-triangular, NRCS Dimensionless, NRCS Triangular and CUHP. Theoretically, volume under a UH has to be drainage area * an inch of rainfall. That may not happen while synthesizing UHs. In case the difference in volume under the synthesized UH and the theoretical volume exceeds the threshold assigned by the user, the model will adjust the UH volume to "match" the theoretical volume.

  • Advanced Forcemain Network Support - The checkbox for Advanced Forcemain Network Support allows the simulation of two or more upstream force mains to one or more downstream force main(s) through a junction chamber.  The link flows and node depths are solved iteratively to maintain the mass balance and the energy balance of the incoming and outgoing flows.  The new network solver is used to calculate the flows in the forcemain pipes and the heads at the junction chambers associated with the force main(s). See Advanced Force Main Network Solution for additional information.

  • If the checkbox flag  is turned on (checked) then the new Advanced Forcemain Network Support will be used during the simulation.

  • If the checkbox flag is turned off (unchecked) then the default force main solution will be used. You will get an error message if there is more than one force main connected to the same junction chamber.

In the example shown below, the upstream force mains are links 947 and FM51, the merging junction chamber is node 52 and the downstream force main is link 53.  As you can see in the graph from the Output Report Manager the flow in link 53 is the sum of the flows in links 947 and FM51.  This example will only work with the new Advanced Forcemain Network Support feature




New Culvert Code for Culverts in ICM 2023.2+ Versions

Culvert inlets and outlets To improve the process of defining culvert inlet and culvert outlet losses for an InfoWorks network, a new fiel...