WSSimObject
WSModelObject > WSBaseNetworkObject > WSNumbatNetworkObject > WSSimObject
A read-only network with simulation results, representing an ICM Sim object, an ICM Risk Analysis Results object, or an ICM Risk Analysis Sim object. The Risk Analysis Results objects contain the results for a number of return periods and summary results. The Risk Analysis Sim objects contain only summary results.
The different return periods for the Risk Analysis Results objects correspond to the timesteps for regular simulations. The names of the methods reflect the usage for regular simulations i.e. to list the return periods for a risk analysis results object, you should use the list_timesteps method.
Methods:
- list_max_results_attributes
- list_results_attributes
- list_results_gis_export_tables
- list_timesteps
- max_flood_contours_export
- max_results_binary_export
- max_results_csv_export
- results_binary_export
- results_csv_export
- results_csv_export_ex
- results_gis_export
- results_path
- run
- run_ex
- status
- success_substatus
- timestep_count
list_max_results_attributes
#list_max_results_attributes ⇒ Array<Array>EXCHANGE
Supported Types: ICM Sim, Risk Analysis Results, Risk Analysis Sim
This method returns attributes that can be exported using the #max_results_binary_export and #max_results_csv_export methods, and returns arrays corresponding to the tabs of the result export dialog in the UI.
[
['Scalar', ['totfl', 'totout', 'totr', ...]],
['Node', ['flooddepth', 'floodvolume', 'flvol', ...]]
]Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | Array<Array> |
list_results_attributes
#list_results_attributes ⇒ Array<Array>EXCHANGE
Supported Types: ICM Sim, Risk Analysis Results
This method returns attributes that can be exported using the #results_binary_export and #results_csv_export methods, and returns arrays corresponding to the tabs of the result export dialog in the UI.
[
['Node', ['flooddepth', 'floodvolume', 'flvol', ...]],
['Link', ['ds_depth', 'ds_flow', 'ds_froude', ...]]
]Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | Array<Array> |
list_results_gis_export_tables
#list_results_gis export_tables ⇒ ArrayEXCHANGE
Supported Types: ICM Sim, Risk Analysis Results, Risk Analysis Sim
Returns an array of the tables that may be exported to GIS using the #results_gis_export method.
- The results for 2D elements is
_2Delements - All links are combined into one GIS layer called
_links
Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | Array |
list_timesteps
#list_timesteps ⇒ ArrayEXCHANGE
Supported Types: ICM Sim, Risk Analysis Results, Risk Analysis Sim
For a normal simulation, this returns an array of the results timesteps for the simulation.
For a risk analysis results object, this returns an array of the return periods for the object.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | Array |
max_flood_contours_export
#max_flood_contours_export(format, ground_model, theme, filename) ⇒ voidEXCHANGE
Supported Types: ICM Sim
Exports the flood contours to files (GIS or ASCII). The ASCII format is the same as produced via the user interface.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| format | String | The fomat, one of mif, tab, shp, or ascii - as in the user interface, geodatabases are not supported. |
| ground_model | Integer, String, WSModelObject | The ground model, which must be a gridded ground model for an ascii export. can be the id (see description), scripting path, or a wsmodelobject of the correct type. if the ground_model id is negative then it represents a tin ground model, i.e. -6 represents the tin ground model with id 6, 9 is a gridded ground model with id 9. |
| theme | Integer, String, WSModelObject | The theme to use for contours - can be the id, scripting path, or a wsmodelobject of the correct type. |
| filename | String | The file to export to. |
max_results_binary_export
#max_results_binary_export(selection, attributes, file) ⇒ voidEXCHANGE
Supported Types: ICM Sim, Risk Analysis Results
Exports the maximum results (and other summary results) for the simulation in a binary file format - the format is documented elsewhere.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| selection | WSModelObject, String, Integer, nil | A selection list object as a wsmodelobject of the correct type, a scripting path, or a model id. if nil then the whole network will be exported. |
| attributes | Array<String>, nil | Attributes to export, e.g. from the #list_results_attributes method, if nil then all attributes are exported. |
| file | String | Filepath to export. |
max_results_csv_export
#max_results_csv_export(selection, attributes, folder) ⇒ voidEXCHANGE
Supported Types: ICM Sim
Exports the maximum results (and other summary results) for the simulation to .CSV files.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| selection | WSModelObject, String, Integer, nil | A selection list object as a wsmodelobject of the correct type, a scripting path, or a model id. if nil then the whole network will be exported. |
| attributes | Array<String>, nil | Attributes to export, e.g. from the #list_results_attributes method, if nil then all attributes are exported. |
| folder | String | Folder to export the .csv files. |
results_binary_export
#results_binary_export(selection, attributes, file) ⇒ voidEXCHANGE
Supported Types: ICM Sim, Risk Analysis Results
Exports the results at each timestep of the simulation in a binary file format - the format is documented elsewhere.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| selection | WSModelObject, String, Integer, nil | A selection list object as a wsmodelobject of the correct type, a scripting path, or a model id. if nil then the whole network will be exported. |
| attributes | Array<String>, nil | Attributes to export, e.g. from the #list_results_attributes method, if nil then all attributes are exported. |
| file | String | Filepath to export. |
results_csv_export
#results_csv_export(selection, folder) ⇒ voidEXCHANGE
Supported Types: ICM Sim
Exports the simulation results in CSV format, corresponding to the CSV results export in the user interface.
If the results multiplier is set to 0, the CSV will be empty.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| selection | WSModelObject, String, Integer, nil | A selection list object as a wsmodelobject of the correct type, a scripting path, or a model id. if nil then the whole network will be exported. |
| folder | String | Folder to export the .csv files. |
results_csv_export_ex
#results_csv_export_ex(selection, attributes, folder) ⇒ voidEXCHANGE
Supported Types: ICM Sim
Similar to #results_csv_export, with an additional attributes parameter.
If the results multiplier is set to 0, the CSV will be empty.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| selection | WSModelObject, String, Integer, nil | A selection list object as a wsmodelobject of the correct type, a scripting path, or a model id. if nil then the whole network will be exported. |
| attributes | Array<String>, nil | Attributes to export, e.g. from the #list_results_attributes method, if nil then all attributes are exported. |
| folder | String | Folder to export the .csv files. |
results_gis_export
#results_gis_export(format, timesteps, options, folder) ⇒ voidEXCHANGE
Supported Types: ICM Sim, Risk Analysis Results, Risk Analysis Sim
Exports simulation results to a GIS data format, similar to the equivalent options in the user interface.
The options for timesteps are:
- nil - this is the equivalent of the 'None' options when selecting timesteps in the UI i.e. it only makes sense if the options hash exports maximum results
- String 'All' - all timesteps, does not include maximum results unless included in the options hash
- String 'Max' - maximum results, alternative to including maximum results in the options hash
- Integer - timestep index, where 0 is the first timestep, and the last valid value is the number of timesteps - 1.
- Array<Integer> - array of timestep indexes, which must all be valid and cannot contain duplicates
The options hash contains the following keys:
| Key | Type | Default | Description |
|---|---|---|---|
| 2DZoneSQL | Array<Array> | Array of arrays, where the array contains: 0 - String - The name of the field to be exported 1 - String - The SQL expression 2 - Integer - Optional value between 0-9 inclusive, representing the number of decimal places. Default is 2. The default is not to export any extra fields for 2D elements. |
|
| AlternativeNaming | Boolean | If this is set then the subfolders / feature datasets used for the export are given simpler but less attractive names which may be helpful if the aim is process the files with software rather than to have a user select and open them in a GIS package. The simple names are <model object id>_<timestep> with the timesteps numbered from zero as with the timesteps parameter of the method and with <model object id>_Max for the maxima.The default is to use the same naming convention as the UI. |
|
| ExportMaxima | Boolean | false | If this is set to true the maximum results are exported. |
| Feature Dataset | String | '' | For GeoDatabases, the name of the feature dataset. |
| Tables | Array<String> | Array of table names from #list_results_gis_exports_table. Must all be valid, and cannot contain duplicates. |
|
| Threshold | Float | The depth threshold below which a 2D element is not exported. This is the equivalent of checking the check-box in the UI and entering a value. The default is to behave as though the check-box is unchecked i.e. all elements are exported. |
|
| UseArcGISCompatibility | Boolean | false | This is the equivalent of selecting the check-box in the UI. |
Parameters
| Name | Type(s) | Description |
|---|---|---|
| format | String | Export format, one of shp, tab, mif, or gdb. |
| timesteps | String, Integer, Array<Integer>, nil | See description. |
| options | Hash, nil | Hash of options (see description) or nil to use defaults. |
| folder | String | The base folder for files to be exported, or path to the .gdb if format is gdb. |
results_path
#results_path ⇒ StringEXCHANGE
Returns full path for results.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | String |
run
#run ⇒ voidEXCHANGE
Supported Types: ICM Sim
Runs (or re-runs) the simulation. This will block the current thread i.e. script execution will halt while this task finishes.
The simulation will be run on the current machine.
run_ex
#run_ex(*args) ⇒ voidEXCHANGE
Supported Types: ICM Sim, Risk Analysis Sim
This method is similar to #run, and is also a blocking operation. There are two versions of this method.
Single Parameter (Options Hash)
#run_ex(options) ⇒ voidThis version takes a single parameter, which is an options hash containing the following keys:
| Name | Type | Default | Description |
|---|---|---|---|
| Server | String | * | The name of the server the simulation may run on, or one of: - . (period) means the local server / computer - * (asterisk) means any available server |
| Threads | Integer | 0 | The number of threads to use, 0 indicates as many threads as possible. |
| SU | Boolean | false | If you are using InfoWorks One you must set this to true. |
| ResultsOnServer | Boolean | true | Whether to store results on server. False stores results locally. |
| DownloadSelection | String | ALL_RESULTS | May be "NO_RESULTS", "SUMMARY_RESULTS" or "ALL_RESULTS". Only applies to cloud databases. |
Parameters
| Name | Type(s) | Description |
|---|---|---|
| options | Hash | Options Hash. See method description |
Two Parameters
#run_ex(server, number_of_threads) ⇒ voidParameters
| Name | Type(s) | Description |
|---|---|---|
| server | String | The name of the server the simulation may run on, or '.' (period) means the local machine, or '*' (asterisk) means any available server. |
| number_of_threads | Integer | The number of threads to use, 0 indicates as many threads as possible. |
status
#status ⇒ StringEXCHANGE, UI
Supported Types: ICM Sim
Returns the status of a simulation.
To monitor for completion of a simulation, the recommended approach is to use the #wait_for_jobs method.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | String, nil | Simulation status, one of none, active, success, or fail. |
success_substatus
#success_substatus ⇒ StringEXCHANGE
Supported Types: ICM Sim
Returns the simulation substatus, if the sim was successful.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | String, nil | Simulation substatus, one of incomplete, warnings, or ok - will return nil if the simulation was not successful. |
timestep_count
#timestep_count ⇒ IntegerEXCHANGE
Supported Types: ICM Sim, Risk Analysis Results, Risk Analysis Sim
Returns the number of results timesteps in the simulation.
Parameters
| Name | Type(s) | Description |
|---|---|---|
| Return | Integer |