An open network. An open network allows access to the network contents, similar to opening the network as a grid or GeoPlan in the UI.

Methods:

• add_scenario
• build_model
• clear_selection
• compare
• compare_scenarios
• control
• csv_export
• csv_import
• current_scenario
• current_scenario= (Set)
• current_timestep
• current_timestep= (Set)
• current_timestep_time
• delete_scenario
• delete_selection
• delete_superfluous_dummy_nodes
• duplicate_scenario_into_network
• each
• each_selected
• expand_short_links
• export_ids
• field_names
• get_demand_categories
• gis_export
• infer_network_values
• isolation_trace
• isolation_trace_ex
• list_gis_export_tables
• list_timesteps
• load_selection
• model_object
• network_model_object
• new_row_object
• objects_in_polygon
• odec_export_ex
• odic_import_ex
• rename_nodes
• reintegrate_scenario
• row_object
• row_object_collection
• row_object_collection_selection
• row_objects
• row_objects_from_asset_id
• row_objects_selection
• run_sql
• save_selection
• scenarios
• search_at_point
• select_in_demand_area
• selection_size
• set_node_namer
• set_projection_string
• snapshot_import
• table
• table_names
• tables
• timestep_count
• timestep_time
• transaction_begin
• transaction_commit
• transaction_rollback
• update_demand_area
• update_demand_diagram_and_network
• validate

add_scenario

#add_scenario(name, based_on, notes) ⇒ void

EXCHANGE, UI

Adds a new scenario to the network.

network.add_scenario('MyNewScenario', nil, 'Some notes...')

Parameters

build_model

#build_model(options, server, instance, database, trusted, username, password) ⇒ void

EXCHANGE, UI

Update the network and control using data in a pre-defined schema in the SQL Server. Allocate customer points to locations in the network. Import multiple tables at once.

net=WSApplication.current_network
options = {
  "Error File" => "D:/temp/error.log",
  "Expansion Log File" => "D:/temp/expansion_log.html",
  "Control ID" => 4823,
  "Demand Diagram ID" =>  4908,
  "Flag" => "SW"
}
net.build_model(options,'.\SQLEXPRESS','','modelbuilder',true,'','')

Parameters

The options hash uses the following keys:

Import Options

Expand short links options

Demand Allocation Options

clear_selection

#clear_selection ⇒ void

EXCHANGE, UI

Clears the current selection, i.e. any WSRowObjects that are currently selected will be deselected.

compare

#compare(other, file_name, options) ⇒ void

EXCHANGE, UI

Compares two networks and outputs the result to a file.

iwdb = WSApplication.current_database
net = WSApplication.current_network.model_object
file_name = "C:/temp/compare.txt"
other_network = iwdb.model_object_from_type_and_id('Geometry',1771)
options = {
  "Version" => 0,
  "Other Version" => 0,
  "Scenario" => "Base",
  "Selection List ID" => 1683,
  "Select Changed Objects" => false,
  "Ignore Flags" => false,
  "Ignore Defaults" => false,
  "Ignore Unique IDs" => false,
  "Use Display Precision" => true,
  "Output Format" => "TEXT"
}
net.compare(other_network, file_name, options)
WSApplication.open_text_view('Compare', file_name, false)

Parameters

Options

compare_scenarios

#compare_scenarios(scenario_A, scenario_B, file_name, options) ⇒ void

EXCHANGE, UI

Compares two scenarios and outputs the result to a file.

net = WSApplication.current_network
file_name = "C:/temp/compare.txt"
options = {
  "Output Format" => "TEXT"
}
net.compare_scenarios("Base","A", file_name, options)
WSApplication.open_text_view('Compare', file_name, false)

Parameters

Options

control

#control ⇒ WSOpenNetwork

UI

This method can only be called from the UI on a WS Pro network object (not a control). It returns another WSOpenNetwork object which is the control. It returns nil if there is no control open in the network.

Example

net=WSApplication.current_network
control = net.control
puts control.current_scenario
net.current_scenario = '1'
control.current_scenario = '1'

control.row_objects('wn_ctl_node').each do |ro|
    puts ro.id
end

csv_export

#csv_export(filename, options) ⇒ void

EXCHANGE, UI

Exports data to CSV.

See WSBaseNetworkObject.csv_export.

csv_import

#csv_import(filename, options) ⇒ void

EXCHANGE, UI

Imports data from CSV.

See WSBaseNetworkObject.csv_import.

current_scenario

#current_scenario ⇒ String

EXCHANGE, UI

Returns the current scenario of the network. If the current scenario is the base scenario, returns the string Base (in English).

Parameters

current_scenario= (Set)

#current_scenario=(name) ⇒ void

EXCHANGE, UI

Sets the current scenario of the network. The scenario must exist.

Parameters

current_timestep

#current_timestep ⇒ Integer

EXCHANGE, UI

The WSOpenNetwork object has a current timestep corresponding to the current timestep results have when opened in the software's UI. It determines the timestep for which the 'result' method of the WSRowObject returns its value. This method returns the index of the current timestep, with the first timestep being index 0 and the final timestep begin timestep_count - 1. The value of -1, representing the 'maximum' 'timestep' is also possible. The initial value when a sim is opened in ICM Exchange will be 0 if there are time varying results, otherwise -1 for the 'maximum' 'timestep'.

puts network.current_timestep_time
=> 0

Parameters

current_timestep= (Set)

#current_timestep=(index) ⇒ void

EXCHANGE

Sets the current network timestep.

Parameters

current_timestep_time

#current_timestep_time ⇒ DateTime

EXCHANGE, UI

Returns the actual time of the current timestep.

puts network.current_timestep_time
=> ?

Parameters

delete_scenario

#delete_scenario(name) ⇒ void

EXCHANGE, UI

Deletes a named scenario from the network. If the deleted scenario is the current scenario, the network will switch to the base scenario.

puts network.current_scenario
=> 'ScenarioBadger'

network.delete_scenario('ScenarioBadger')

puts network.current_scenario
=> 'Base'

Parameters

delete_selection

#delete_selection ⇒ void

EXCHANGE, UI

Deletes the currently selected objects from the network, in the current scenario.

delete_superfluous_dummy_nodes

#delete_superfluous_dummy_nodes(tables, field) ⇒ void

EXCHANGE, UI

Deletes all objects in node tables where the named field (field parameter) is set to Y, and the object is not the upstream or downstream node in one of the tables in the array.

This method is used in conjunction with the open data import centre, where dummy nodes have been added at the ends of links (e.g. because they have been imported from a GIS where they are represented as point objects) but the links have since been deleted.

Parameters

duplicate_scenario_into_network

#duplicate_scenario_into_network(scenario, network) ⇒ void

EXCHANGE, UI

Duplicates a scenario from a network or control to the base scenario in another empty network or control.

iwdb = WSApplication.current_database
net = WSApplication.current_network
new_network = iwdb.model_object_from_type_and_id('Geometry',5034)
net.duplicate_scenario_into_network('A',new_network)

control = net.control
new_control = iwdb.model_object_from_type_and_id('Control',5035)
control.duplicate_scenario_into_network('A',new_control)

Parameters

each

#each { |ro| ... } ⇒ WSRowObject

EXCHANGE, UI

Iterates through each object in the network.

Parameters

each_selected

#each_selected { |ro| ... } ⇒ WSRowObject

EXCHANGE, UI

Iterates through each selected object in the network.

Parameters

expand_short_links

#expand_short_links(options) ⇒ void

EXCHANGE, UI

Expands the selected links, similar to the user interface 'Expand Short Links' tool. This is used to visually expand generated link objects like valves, meters, or pumping stations.

The links must be selected, and their table type should be included in the Tables array of the options hash.

The options hash must exist, and has the following keys:

Parameters

export_ids

#export_ids(filename, options) ⇒ void

EXCHANGE, UI

Exports the IDs of WSRowObjects to a file, grouped by table.

The options hash has the following keys:

Parameters

field_names

#field_names(table) ⇒ Array<String>

EXCHANGE, UI

Returns the field names for a given table.

network.field_names('wn_node').each { |s| puts s }

Parameters

get_demand_categories

#get_demand_categories ⇒ Array<String>

EXCHANGE

Returns all demand categories referenced in this network.

Parameters

gis_export

#gis_export(format, options, location) ⇒ void

EXCHANGE, UI

Exports the network data to GIS format. See the WSNumbatNetworkObject.gis_export method.

infer_network_values

#infer_network_values(inference, ground_model) ⇒ void

EXCHANGE, UI

Runs an inference object on the network.

Parameters

isolation_trace

#isolation_trace(selection_to_be_isolated, close_downstream, assume_valve_at_meter, selection_ignore_valves, selection_closed_links, selection_isolated, selection_customer_points, selection_spatial_data, report) ⇒ Boolean

EXCHANGE

Performs an isolation trace on the network.

Parameters

isolation_trace_ex

#isolation_trace_ex(selection_to_be_isolated, close_downstream, assume_valve_at_meter, selection_ignore_valves, selection_closed_links, selection_isolated, selection_customer_points, selection_spatial_data, report, close_at) ⇒ Boolean

EXCHANGE

Performs an isolation trace on the network. This method has an extra close_at parameter.

Parameters

close_at [Hash] close options:

Hash values

To ignore area changes

close_at = { "Area Change" => false}

list_gis_export_tables

#list_gis_export_tables ⇒ Array<String>

EXCHANGE

Returns the tables that can be exported using the #gis_export method.

Parameters

list_timesteps

#list_timesteps ⇒ Array<DateTime>

EXCHANGE, UI

Returns the times of all timesteps, in order.

Parameters

load_selection

#load_selection(selection_list) ⇒ void

EXCHANGE, UI

Selects objects in the network from the selection list object.

Parameters

model_object

#model_object ⇒ WSModelObject

EXCHANGE, UI

Returns a WSModelObject (or derived class) associated with this network.

If the network was loaded from a sim, then the model object of that sim will be returned. This is different from #network_model_object which always returns the network.

Parameters

network_model_object

#network_model_object ⇒ WSModelObject

EXCHANGE, UI

Returns the WSModelObject (or derived class) associated with this network.

If the network was loaded from a sim, then the model object of that network will be returned. This is different from #model_object which would return the sim.

Parameters

new_row_object

#new_row_object(type) ⇒ WSRowObject

EXCHANGE, UI

Creates a new object in this network. This must be done within a network transaction, and you must set a primary ID for the object before you can write changes to it.

Parameters

objects_in_polygon

#objects_in_polygon(polygon, type) ⇒ Array<WSRowObject>

EXCHANGE, UI

Returns an array of the WSRowObject objects inside the polygon geometry, matching the type parameter.

When using an array of strings as the type, all values must be unique (no duplicates) and cannot contain a category and a table within the same category.

Parameters

odec_export_ex

#odec_export_ex(format, config, options, table, *args) ⇒ void

EXCHANGE, UI

Exports network data using the Open Data Export Centre.

See WSBaseNetworkObject.odec_export_ex.

odic_import_ex

#odic_import_ex(format, config, options, table, *args) ⇒ Array<WSRowObject>

EXCHANGE, UI

Imports and updates network data using the Open Data Import Centre, returning an array of the objects created or updated in the process. Objects may also be deleted, but these are not returned / listed.

See WSBaseNetworkObject.odec_import_ex.

Parameters

rename_nodes

#rename_nodes(control, options) ⇒ void

EXCHANGE

Renames all existing nodes in the network. See also #set_node_namer method.

The options hash has the following keys:

• 'Method' (String) : one of UK, IRELAND, XY8, XY10, XY12, XY14, or CUSTOM
• 'Custom Pattern' (String) : if Method is 'CUSTOM', this is the custom string format, leave unset otherwise

Parameters

reintegrate_scenario

#reintegrate_scenario(name) ⇒ void

EXCHANGE, UI

Reintegrates a scenario into the base.

net = WSApplication.current_network
net.reintegrate_scenario('A')

Parameters

row_object

#row_object(type, id) ⇒ WSRowObject?

EXCHANGE, UI

Returns a specific row object by type and ID.

node = network.row_object('wn_node', 'ST543643')
raise "Could not get node" if node.nil?

Parameters

row_object_collection

#row_object_collection(type) ⇒ WSRowObjectCollection

EXCHANGE, UI

Returns all row objects of a given type as a WSRowObjectCollection.

Parameters

row_object_collection_selection

#row_object_collection_selection(type) ⇒ WSRowObjectCollection

EXCHANGE, UI

Returns all selected row objects of a given type as a WSRowObjectCollection.

Parameters

row_objects

#row_objects(type) ⇒ Array<WSRowObject>

EXCHANGE, UI

Returns all row objects of a given type in an Array.

Parameters

row_objects_from_asset_id

#row_objects_from_asset_id(type, id) ⇒ Array<WSRowObject>

EXCHANGE, UI

Returns all row objects of a given type with this Asset ID. This method is useful when working with imported link objects, where you may not know the multi-part ID.

Asset ID's are not guaranteed to be unique, so there may be multiple results. You can use the first Array method to access the first object.

nodes = network.row_objects_from_asset_id('wn_node', 'ST543643')
puts nodes.first['asset_id']
=> 'ST543643'

You can also create your own method which enforces a single result, returning nil if no object is found or multiple objects are found:

def unique_row_object_from_asset_id(network, type, id)
  nodes = network.row_objects_from_asset_id(type, id)
  return (nodes.size != 1) ? nil : nodes.first
end

Parameters

row_objects_selection

#row_objects_selection(type) ⇒ Array<WSRowObject>

EXCHANGE, UI

Returns all selected row objects of a given type in an Array.

Parameters

run_sql

#run_sql(table, query) ⇒ void

EXCHANGE, UI

Runs a SQL query on this network.

The SQL query can include multiple clauses, including saving results to a file, but cannot use any of the options that open results or prompt grids.

Parameters

save_selection

#save_selection(selection_list) ⇒ void

EXCHANGE, UI

Saves the current selection (in the current scenario) to an already existing selection list model object.

Parameters

scenarios

#scenarios { |s| ... } ⇒ String

EXCHANGE, UI

Iterates through the scenarios, yielding a String of each scenario name. The base scenario is included as the string Base in English.

  network.scenarios { |scenario| puts scenario }

  network.scenarios do |scenario|
    puts scenario
  end

Parameters

search_at_point

#search_at_point(x, y, distance, types) ⇒ Array<WSRowObject>

EXCHANGE, UI

Find all objects within a distance of a given point.

When using an array of strings as the type, all values must be unique and cannot contain a category and a table within that category. This is similar to the WSRowObject.objects_in_polygon method.

Parameters

select_in_demand_area

#select_in_demand_area(rowobject, open_control) ⇒ void

EXCHANGE, UI

Use existing WSOpenNetwork method each_selected to view selection.

Returns non zero if unable to select.

Example

database = WSApplication.open

#need nw and ctl
geometry_id = 7
control_id = 3

#get the relevant network and control
network = database.model_object_from_type_and_id('geometry',geometry_id)
imoc = database.model_object_from_type_and_id('control',control_id)
clds = imoc.open()
nlds = network.open()

@ro
#show the demand areas
nlds.row_objects('wn_demand_area').each do |da|
    id = da['area_id']
    if(id=="35")
        @ro = da;
    end
    puts id
end

#pass a single row object or an array
nlds.select_in_demand_area(@ro,clds);
#nlds.select_in_demand_area(nlds.row_objects('wn_demand_area'))

#show selected items
nlds.each_selected() do |itm|
    puts itm.table() + ' ' + itm.id()
end

nlds.close()
clds.close()    
database.close()    

Parameters

selection_size

#selection_size ⇒ Integer

EXCHANGE, UI

Returns the number of objects currently selected.

Parameters

set_node_namer

#set_node_namer(method, custom) ⇒ void

EXCHANGE

Sets the auto-naming convention for new nodes.

Parameters

set_projection_string

#set_projection_string(string) ⇒ void

EXCHANGE

Sets the map projection string. The format of the string depends on the current map control.

Compatible projection strings or MapXTreme can be found in C:\Program Files\Common Files\MapInfo\MapXtreme\VERSION\MapInfoCoordinateSystemSet.xml, where VERSION will depend on the current application version.

E.g. for British National Grid [EPSG 27700]:

<gml:srsID>
  <gml:name gml:codeSpace="mapinfo">coordsys 8,79,7,-2,49,0.9996012717,400000,-100000</gml:name>
</gml:srsID>

The projection string is: 8,79,7,-2,49,0.9996012717,400000,-100000.

Parameters

snapshot_import

#snapshot_import(file) ⇒ void

EXCHANGE, UI

Imports a snapshot file into the network from a file.

Parameters

table

#table(name) ⇒ WSTableInfo

EXCHANGE, UI

Returns a WSTableInfo object for a specific table in this network.

Parameters

table_names

#table_names ⇒ Array<String>

EXCHANGE, UI

Returns the names of all tables in this network.

Parameters

tables

#tables ⇒ Array<WSTableInfo>

EXCHANGE, UI

Returns an array of WSTableInfo objects for the tables in this network.

Parameters

timestep_count

#timestep_count ⇒ Integer

EXCHANGE, UI

Returns the number of result timesteps, not including the maximum timestep.

Parameters

timestep_time

#timestep_time(timestep_no) ⇒ DateTime

EXCHANGE, UI

Returns the actual time of the timestep index provided.

Parameters

transaction_begin

#transaction_begin ⇒ void

EXCHANGE, UI

Begins a transaction, during which you can modify network data such as adding/removing objects or changing fields. Most changes to a network must be within a transaction.

A transaction can be ended with #transaction_commit (to save the changes) or #transaction_rollback (to abandon them).

transaction_commit

#transaction_commit ⇒ void

EXCHANGE, UI

Commits any changes to the network since #transaction_begin.

transaction_rollback

#transaction_rollback ⇒ void

EXCHANGE, UI

Rolls back (ends) the transaction, which reverts any changes made since #transaction_begin.

This should be used with caution if you are storing references to WSRowObjects or associated data, as this may break references and cause an exception when you attempt to access or work with them.

update_demand_area

#update_demand_area(open_network, open_control, options) => WSValidations

EXCHANGE, UI

Equivalent of "Update demand area(s)" in the UI.

Returns validation result collection.

Example

require 'date'

database = WSApplication.open

#get the relevant network and control
network = database.model_object_from_type_and_id('geometry',1081)
imoc = database.model_object_from_type_and_id('control',1082)
clds = imoc.open()
nlds = network.open()

#show the demand areas
nlds.row_objects('wn_demand_area').each do |da|
    id = da['area_id']
    puts id
end

begin
    nlds.transaction_begin()
    hashOptions = Hash.new
    hashOptions['demand_diagram'] = 1086
    hashOptions['live_data_config'] = 1083
    validation_results = nlds.update_demand_area(nlds.row_objects('wn_demand_area'),clds,hashOptions)
    nlds.transaction_commit()

    validation_results.each do |v|            
        puts "Type: #{v.type}\nCode: #{v.code}\nPriority: #{v.priority}\nObject type: #{v.object_type}\nObject id: #{v.object_id}\nField: #{v.field_description}\nMessage: #{v.message}\n\n"
    end

rescue => exception
    print("#{exception.message}")
    nlds.transaction_rollback
end

nlds.row_objects('wn_demand_area').each do |da|
    ["area_id",
    "area_id_flag",
    "aznp",
    "aznp_flag",
    "aznp_node",
    "aznp_node_flag",
    "background_losses",
    "bounding_links",
    "bounding_links_flag",
    "bounding_links2",
    "calculated_spec_cons",
    "calibration_start",
    "calibration_start_flag",
    "demand_interpolation",
    "demand_interpolation_flag",
    "excess_unaccounted_for_water",
    "icf",
    "icf_flag",
    "ignore_leakage",
    "leakage_application",
    "leakage_application_flag",
    "leakage_profile",
    "leakage_profile_flag",
    "length_of_mains",
    "measurement_period",
    "measurement_period_flag",
    "minimum_night_flow",
    "multiplier",
    "multiplier_flag",
    "net_inflow",
    "number_unmetered_properties",
    "pcf",
    "pcf_flag",
    "pcf_method",
    "pcf_method_flag",
    "polygon_id",
    "polygon_id_flag",
    "total_inflows",
    "total_outflows",
    "unaccounted_for_water",
    "unmetered_demand",
    "unmetered_demand_flag",
    "unmetered_dom_nu",
    "unmetered_dom_nu_flag",
    "validation"].each do |field|
        puts "#{field}:#{da[field]}"
    end
    puts "\n"
end

nlds.close()
clds.close()    
database.close()    

Parameters

update_demand_diagram_and_network

#update_demand_diagram_and_network(demand_areas, open_control, options, optionsPropertyBased, optionsDirect)

EXCHANGE, UI

Equivalent of "Update demand diagram and network" in the UI.

Returns a hash of changes to network with a count of deleted, inserted, and modified objects, and the number of settings changed.

Example

database = WSApplication.open

geometry_id = 7
control_id = 3
ddg_id = 16
ldc_id = 4

#get the relevant network and control
network = database.model_object_from_type_and_id('geometry',geometry_id)
imoc = database.model_object_from_type_and_id('control',control_id)
clds = imoc.open()
nlds = network.open()

#show the demand areas
nlds.row_objects('wn_demand_area').each do |da|
    id = da['area_id']
    puts id
end

nlds.transaction_begin()
begin
    hashOptionsPropertyBased = Hash.new
    hashOptionsPropertyBased["update_demand_diagram"] = true;
    hashOptionsPropertyBased["update_demand_in_network"] = true;
    hashOptionsPropertyBased["scale_existing_demand"] = false;
    hashOptionsPropertyBased["update_leakage_in_network"] = true;
    hashOptionsPropertyBased["leakage_items_property_based_demand"] = false;#if false uses avg demad

    hashOptionsDirect = Hash.new
    hashOptionsDirect["update_demand_diagram"] = true;
    hashOptionsDirect["update_leakage_in_network"] = true;

    hashOptions = Hash.new
    hashOptions['demand_diagram'] = ddg_id
    hashOptions['live_data_config'] = ldc_id

    arr = nlds.update_demand_diagram_and_network(nlds.row_objects('wn_demand_area'),clds,hashOptions, hashOptionsPropertyBased,hashOptionsDirect)

    arr.each do | key, value |
        puts "#{key}:#{value}"
    end 

    nlds.transaction_commit()
    #commit changes to network
    #network.commit("scripted update");
rescue => exception
    print("#{exception.message}")
    nlds.transaction_rollback()
end

nlds.close()
clds.close()    
database.close()

validate

#validate(scenarios) ⇒ WSValidations

EXCHANGE, UI

Validates a scenario (or multiple scenarios) and returns a WSValidations object.

When validating multiple scenarios, the WSValidation.scenario method can be used to filter each validation result.

Parameters