An object that exist in the database tree such as model groups, networks, selection lists, and stored queries.

Methods that return a WSModelObject may return a derived class, for example a WSNumbatNetworkObject for network types, or WSSimObject for simulations.

Methods:

• != (Does Not Equal)
• == (Equals)
• [] (Get Field)
• []= (Set Field)
• bulk_delete
• children
• comment
• comment= (Set)
• compare
• copy_here
• csv_import_tvd
• deletable?
• delete
• delete_results
• export
• find_child_model_object
• id
• import_all_sw_model_objects
• import_data
• import_grid_ground_model
• import_infodrainage_object
• import_new_model_object
• import_new_model_object_from_generic_csv_files
• import_new_sw_model_object
• import_tvd
• modified_by
• name
• name= (Set)
• new_model_object
• new_risk_analysis_run
• new_run
• new_synthetic_rainfall
• open
• parent_id
• parent_type
• path
• type
• update_to_latest

!= (Does Not Equal)

#!=(other_mo) ⇒ Boolean

EXCHANGE, UI

Checks if this model object is not the same as another model object (inequality check).

== (Equals)

#==(other_mo) ⇒ Boolean

EXCHANGE, UI

Checks if this model object is the same as another model object (equality check).

[] (Get Field)

#[(field)] ⇒ Any

EXCHANGE, UI

Returns the value of a field.

[]= (Set Field)

#[(field)]=(value) ⇒ void

EXCHANGE, UI

Sets the value of a field.

Parameters

bulk_delete

#bulk_delete ⇒ void

EXCHANGE, UI

Permanently deletes the object and all of its children, skipping the recycle bin.

This method works even if the object has children or is used in a simulation, which does not follow the user interface convention. For a safer version of this method, see #delete.

children

#children ⇒ WSModelObjectCollection

EXCHANGE, UI

Returns the children of the object.

Parameters

comment

#comment ⇒ String

EXCHANGE

Returns the comment, a.k.a the description in the user interface.

Parameters

comment= (Set)

#comment=(text) ⇒ void

EXCHANGE

Sets the comment, a.k.a the description in the user interface.

Parameters

compare

#compare(other) ⇒ Boolean

EXCHANGE

Compares this model object to another, both model objects must be the same type of version controlled object or simulation results.

Simulation results can only be compared if they are both from the current database.

if mo.compare(mo2) then
  puts 'Networks are the same!'
else
  puts 'Networks are not the same!'
end

Parameters

copy_here

#copy_here(object, copy_sims, copy_ground_models) ⇒ WSModelObject

EXCHANGE, UI

Copies a model object and any children as a child of this object, returning the new model object. The model object being copied could be from the same database, or another database such as a transportable database.

Parameters

csv_import_tvd

#csv_import_tvd(file, name, config_file) ⇒ Array

EXCHANGE

Performs an import of time varying data into an asset group, creating one or more 'time varying data' objects in the same manner as the user interface when the import time varying data from generic CSV option is used.

Parameters

deletable?

#deletable? ⇒ Boolean

EXCHANGE

Whether this model object can be deleted using the #delete method, which follows the user interface rules: has no children, and is not used in a simulation.

Parameters

delete

#delete ⇒ void

EXCHANGE, UI

Deletes the object, provided it meets the user interface rules: has no children, and is not used in a simulation.

This is a safer alternative to the #bulk_delete method, which ignores these rules.

delete_results

#delete_results ⇒ void

EXCHANGE

Deletes the results, if this object is a simulation.

export

#export(path, format) ⇒ void

EXCHANGE

Exports the model object in the appropriate format.

The formats permitted depend on the object type. The format string may affect the actual data exported as well as the format in which the data is exported e.g. for rainfall events the parameter 'CRD' means that the Catchment Runoff Data is exported.

When the format is the empty string the data is exported in the InfoWorks text file format. This format may be used for:

• Inflow
• Level
• Infiltration
• Waste Water
• Trade Waste
• Rainfall Event (non-synthetic)
• Pipe Sediment Data
• Observed Flow Event
• Observed Depth Event
• Observed Velocity Event
• Layer List ( this is a different file format but still termed the 'InfoWorks file' in the user interface).
• Regulator (from 6.0)

For rainfall events the following parameters cause the export of other data in a text file format:

• CRD - Catchment Runoff Data
• CSD - Catchment Sediment Data
• EVP - Evaporation
• ISD - Initial Snow Data
• TEM - Temperature Data
• WND - Wind Data

For pollutant graphs the appropriate pollutant graph code causes the export of that pollutant's data in the text file format.

If the format is 'CSV' the file will be exported in 'InfoWorks CSV' format for the following object types:

• Level
• Infiltration
• Inflow
• Observed Flow
• Observed Depth
• Observed Velocity
• Rainfall Event (synthetic - main rainfall data)
• Regulator
• Damage Function (from version 6.5)
• Waste Water (from a version 7.5 patch)
• Trade Waste (from a version 7.5 patch)

The results obtained by risk analysis runs may be exported as follows:

For Risk Analysis Results objects (known in ICM Exchange as Risk Calculation Results) the files may be exported by using the following in the format field:

• "Receptor Damages"
• "Component Damages"
• "Code Damages"
• "Impact Zone Damages"
• "Category Damages"
• "Inundation Depth Results"

For Risk Analysis Sim objects (known in ICM Exchange as Damage Calculation Results) the files may be exported by using the following in the format field:

• "Receptor vs Code"
• "Receptor vs Component"
• "Code vs Component"
• "Impact Zone vs Code"
• "Impact Zone Code vs Component"
• "Category Code vs Component"

For dashboards in InfoAsset Manager the format must be 'html', and the filename the name of the HTML file. Note in this case that other files are exported alongside the html file in the same folder. The names of these files are fixed for each individual dashboard object in the database so exporting the same dashboard object multiple times to different HTML files in the same folder will not give the intended results, you should instead export them to different folders.

Parameters

find_child_model_object

#find_child_model_object(type, name) ⇒ WSModelObject?

EXCHANGE, UI

Finds a child model object of a given type and name.

Parameters

id

#id ⇒ Integer

EXCHANGE, UI

Returns the ID of this model object.

import_all_sw_model_objects

#import_all_sw_model_objects(file, format, scenario, logfile) ⇒ Array<WSModelObject>

EXCHANGE

Imports all SWMM model objects from a supported file. Object types imported:

• SWMM Network
• Inflow
• IWSW Run
• IWSW Time Patterns
• Selection List
• Level
• Rainfall Event
• IWSW pollutograph
• IWSW Climatology
• Regulator

This model object must be of a suitable type to contain the model objects imported.

Parameters

import_data

#import_data(format, file) ⇒ void

EXCHANGE

Imports data into this object.

This is only relevant for rainfall events and pollutographs, because they contain multiple pages of data which must be imported and exported separately. You have the choice of either:

• Creating an empty object and importing all the data items using this method
• Importing the first data item into a new object using #import_new_model_object and importing subsequent items into the object using this method - in the case of rainfall events the first item must be the rainfall, in the case of pollutographs is can be any item

Both InfoWorks CSV and InfoWorks file formats are supported. The parameter is 'CSV' for CSV files or some other string for the InfoWorks files.

For rainfall events the formats are SMD, EVP, SOL, WND, TEM, CSD, ISD, CRD and RED - for RED you can also put nil or ''. These are as documented in the main product documentation.

For pollutographs the format name is the pollutograph code.

CSV files import into the blob based on data in the CSV file.

For rainfall events the CSV files may only be used for the time varying data i.e Rainfall, Temperature, Wind, Evaporation, Solar Radiation and Soil Moisture Deficit.

mo_rain.import_data('CSV', 'C:/temp/MyRain_EVP.csv')
mo_rain.import_data('SMD', 'C:/temp/MyRain.smd')
mo_pollutograph.import_data('CSV', 'C:/temp/P.csv')

Parameters

import_grid_ground_model

#import_grid_ground_model(polygon, files, options) ⇒ void

EXCHANGE

Imports a gridded ground model. This WSModelObject must be a model group or asset group.

The options hash contains the following options:

model_group = database.model_object_from_type_and_id('Model Group', 2)
files = ['C:/temp/small_grid.asc']
options = {
  'ground_model_name' => 'my_ground_model',
  'data_type' => 'badger',
  'cell_size' => 5.0,
  'unit_multiplier' => 1.0,
  'xy_multiplier' => 1.0,
  'integer_format' => false,
  'use_polygon' => false
}
model_group.import_grid_ground_model(nil, files, options)

Parameters

import_infodrainage_object

#import_infodrainage_object(file, type, log) ⇒ WSModelObject

EXCHANGE

Imports an InfoDrainage object. This WSModelObject must be a model group.

Parameters

import_new_model_object

#import_new_model_object(type, name, format, file, event) ⇒ WSModelObject

EXCHANGE

Imports a new model object from a file, as a child of this WSModelObject. This must be a suitable type to contain the new model object.

Permitted types are:

• Inflow
• Level
• Ground Infiltration
• Waste Water
• Trade Waste
• Rainfall Event (non-synthetic)
• Pipe Sediment Data
• Observed Flow Event
• Observed Depth Event
• Observed Velocity Event
• Layer List (this is a different file format but still termed the 'InfoWorks file' in the user interface)
• Regulator
• Damage Function
• Pollutograph

Permitted formats are:

• An empty string - for InfoWorks format files
• CSV for InfoWorks format CSV files (not available for layer lists, or damage functions)
• CSV for Pollutographs (the data imported will depend on the CSV file)
• The 3 letter pollutograph code

You can only import one pollutant, if you wish to import more into the same InfoWorks object you can use the #import_data method. You can also use that method to import additional data into Rainfall Events.

rainfall = model_group.import_new_model_object('Rainfall Event', 'The Rainfall', '', 'C:/temp/1.red')

Parameters

import_new_model_object_from_generic_csv_files

#import_new_model_object_from_generic_csv_files(type, name, file, config) ⇒ Array<WSModelObject, String>

EXCHANGE

Imports a new model object using the generic CSV importer, as a child of this WSModelObject. This must be a suitable type to contain the new model object.

It requires a config file previously set up in the UI.

Permitted types are:

• Inflow
• Level
• Infiltration
• Rainfall Event (non-synthetic)
• Pipe Sediment Data
• Observed Flow Event
• Observed Depth Event
• Observed Velocity Event
• Regulator

The return value is an array with 2 elements. The first element is the WSModelObject created. The second element is either nil or a string of the warning message that would appear in the UI .

Parameters

import_new_sw_model_object

#import_new_sw_model_object(type, format, file, scenario, log) ⇒ WSModelObject

EXCHANGE

Imports a new SWMM model object as a child of this WSModelObject. This must be a suitable type to contain the new model object.

Permitted types are:

• Inflow
• IWSW Run
• IWSW Time Patterns
• Selection List
• Level
• Rainfall Event
• IWSW pollutograph
• IWSW Climatology
• Regulator

new_swmm = model_group.import_new_sw_model_object('Rainfall Event', 'INP', 'C:/temp/1.inp', '', 'C:/temp/log.txt')

Parameters

import_tvd

#import_tvd(file, format, event) ⇒ void

EXCHANGE

Imports event data into an existing object.

If the format is 'CSV' this expects the 'InfoWorks CSV file' format, and imports this into an existing event, overwriting any data already there.

If the format is 'RED' and the type of the object is a rainfall event, this will import the data in event file format into an existing event, overwriting any data already there.

Parameters

modified_by

#modified_by ⇒ String

EXCHANGE, UI

Returns the username which last modified the object. This may be different from the latest commit of a version controlled network.

name

#name ⇒ String

EXCHANGE, UI

Returns the name of this object.

name= (Set)

#name=(new_name) ⇒ void

EXCHANGE, UI

Sets the name of this object.

Parameters

new_model_object

#new_model_object(type, name) ⇒ WSModelObject

EXCHANGE, UI

Creates a new model object as a child of this object - the type must be valid for this object.

Scripts that are running in the user interface are unable to create most types of model objects, the only exceptions being Selection Lists and Selection List Groups. The full functionality of this method is only available in Exchange.

Runs cannot be created using this method, they are created using #new_run or #new_risk_analysis_run.

Parameters

Exceptions

• unrecognised type - if the type is not a valid scripting type
• sims cannot be created directly - if an attempt is made to create a sim
• invalid child type for this object - if the new type may not be a child of this object type
• name already in use - if the name is in use by another model object (that is also a child of this object), or globally if this is a version controlled type with a standalone database
• licence and/or permissions do not permit creation of a child of this type for this object - if this type of object cannot be created for licensing and/or permissions reasons
• unable to create object - if the call fails for some other reason

new_risk_analysis_run

#new_risk_analysis_run(name, damage_function, runs, param) ⇒ WSRiskAnalysisRunObject

EXCHANGE

Creates a new risk analysis run object.

Parameters

new_run

#new_run(name, network, commit_id, rainfalls_and_flow_surveys, scenarios, options) => WSModelObject

EXCHANGE

Creates a new run. This WSModelObject must be a model group.

The method can take arrays as parameters for both the rainfalls and flow surveys and for the scenarios. In the same way that dropping multiple rainfall events and flow surveys into the drop target on the schedule run dialog and selecting multiple scenarios on it yield multiple simulations for a run, so calling this method with arrays of values and with synthetic rainfall events which have multiple parameters (singly or in an array) will yield multiple sims for the run.

The #run method which actually runs simulations is a method of the individual sim objects below the run, which can be accessed by using the #children method of the WSModelObject returned by this method.

The rainfalls_and_flow_surveys parameter can be:

• nil - in this case the run will be a dry weather flow run
• a WSModelObject which is a rainfall event or a flow survey
• the scripting path of a rainfall event or a flow survey as a string
• the ID of a rainfall event
• a negative number equal to -1 times the ID of a flow survey e.g. -7 means the Flow Survey with ID 7.
• An array. If the parameter is an array, then if the length of the array is 0 then the event will be a dry weather flow run, otherwise all the array elements must be one of 2 - 5 above. The array may not contain duplicates otherwise an exception will be thrown.

Parameters

Exceptions

• new_run : runs may only be created in model groups - the run must only be created in a model group
• new_run : name already in use - if the run name is already in use

new_synthetic_rainfall

#new_synthetic_rainfall(name , type, params) ⇒ void

EXCHANGE

Creates a new synthetic rainfall model object as a child of this WSModelObject. Permitted generator types are:

• UKRain
• FEHRain
• ReFHRain
• GermanRain
• HKRain
• HK5thEdRain
• AUSRain
• FRQRain
• FRRain
• MYRain
• MY2015Rain
• USRain
• ChineseRain
• ChicagoRain

The params hash contains the following.

Parameters

Exceptions

• synthetic rainfall events may only be created in model groups : the rainfall event must be created in a model group.
• name already in use : if the rainfall event name is already in use.
• rainfall type XXXX cannot be created by scripting : input type one of the following FEH2013, FEH2022, AUS2016Rain, NOAARain which cannot be created using scripting since they need external software.
• rainfall type XXXX not found : input type not valid.
• parameter 3 is not a Hash : input params is not a valid hash.
• unable to load DLL : problem loading rainfall generator software.

open

#open ⇒ WSModelObject

EXCHANGE, UI

Only available for model objects of a network type or sim.

Opens the network and returns a WSOpenNetwork object. When this method is called on a sim, the network and results are opened. An exception will be thrown if the simulation did not succeed or the results are inaccessible.

Note that when you open the results of a simulation:

• The network is opened as read only
• The current scenario is set to the scenario used for the simulation
• The current scenario cannot be changed
• As with the behaviour in the UI of the software, the network with the results loaded has a current timestep. The results start by being opened at the first timestep (timestep 0) unless there are only maximum results in which case they are opened as the maximum results timestep.

Parameters

parent_id

#parent_id ⇒ Integer

EXCHANGE, UI

Returns the ID of this object's parent. This will be 0 if the object is in the root of the database.

parent_type

#parent_type ⇒ String

EXCHANGE, UI

Returns the type of this object's parent. This will be 'Master Database' if the object is in the root of the database.

path

#path ⇒ String

EXCHANGE, UI

Returns the scripting path of this object.

type

#type ⇒ String

EXCHANGE, UI

Returns the type of this model object.

update_to_latest

#update_to_latest ⇒ void

EXCHANGE

Updates a run model object, equivalent to the 'update to latest version of network' button in the run view of the user interface. The following conditions apply:

• The 'Working' field must be set to true
• There must be no uncommitted changes for the network used in the run
• All scenarios that were included in the scenarios list must be present and validated