Network

The network API gives you access to all assets in a network, along with their readings and other metadata. Many extensions make use of it, so it’s a great starting point to get familiar with Qatium’s SDK.

Accessing the network

At the moment, you can only operate on the currently loaded network. Once it is loaded, you can access it by using the window.qatium.network object in your browser console:

const sdk = window.qatium
const network = sdk.network

Or by using the network object in the Plugin SDK

import type { SDK, PluginI } from "@qatium/plugin/engine";

class MyPlugin implements PluginI {
  run(sdk: SDK) {
    const network = sdk.network;
  }
}

In the following sections, we will refer to the Network object as network without the window.qatium prefix.

Asset Queries

getAsset()

Returns an Asset object representing the asset with the given ID, or undefined if it doesn’t exist.

Method signature

getAsset(assetId: string) : Asset | undefined

Example

Get an asset from Magnetic Island. A tank, in this case:

const asset = network.getAsset('Horseshoebay')

getAssets()

Returns an array of Asset objects that match the given filter function. If no filter is provided, all assets are returned.

Method signature

getAssets(filter?: function) : Asset[]

Examples

Get all assets in Magnetic Island:

const allAssets = network.getAssets()

Get all assets in Magnetic Island that are tanks:

const tanks = network.getAssets((asset) => asset.type === 'Tank')

Returns an array of assets with IDs Horseshoebay, Cocklebay, and Nellybay:

[
  {
    "id": "Horseshoebay",
    ...
  },
  {
    "id": "Cocklebay",
    ...
  },
  {
    "id": "Nellybay",
    ...
  }
]

For your convenience, the following methods return an array of specific types of assets:

getJunctions()

Returns an array of Junction objects that match the given filter function. If no filter is provided, all junctions are returned.

Method signature

getJunctions(filter?: function) : Junction[]

getTanks()

Method signature

Returns an array of Tank objects that match the given filter function. If no filter is provided, all tanks are returned.

getTanks(filter?: function) : Tank[]

getPipes()

Returns an array of Pipe objects that match the given filter function. If no filter is provided, all pipes are returned.

Method signature

getPipes(filter?: function) : Pipe[]

getPumps()

Returns an array of Pump objects that match the given filter function. If no filter is provided, all pumps are returned.

Method signature

getPumps(filter?: function) : Pump[]

getSupplySources()

Method signature

Returns an array of SupplySource objects that match the given filter function. If no filter is provided, all supply sources are returned.

getSupplySources(filter?: function) : SupplySource[]

getValves()

Method signature

Returns an array of Valve objects that match the given filter function. If no filter is provided, all valves are returned.

getValves(filter?: function) : Valve[]

Zone Queries

getZone()

Method signature

Returns a Zone object representing the zone with the given ID, or undefined if it doesn’t exist.

getZone(zoneID: string) : Zone | undefined

Example

const zone = network.getZone('Z1')

getZones()

Returns an array of Zone objects that match the given filter function. If no filter is provided, all zones are returned. If no zones are defined in the network, an empty array is returned.

Method signature

getZones(filter?: function) : Zone[]

Example

Get all zones in the network:

const allZones = network.getZones()

Get zones with ID Arcadia DMA or Horseshoe Bay DMA:

const zones = n.getZones(
  (zone) => zone.id === 'Arcadia DMA' || zone.id === 'Horseshoe Bay DMA'
)

Network Queries

isScenarioActive()

Returns true if a network version scenario is active, or false if the base network version is active.

isSimulationLoading()

Returns true if the simulation is still loading, or false if it has finished loading.

isSimulationPeriodCompleted()

Returns true if the current simulation period has finished, or false if it hasn’t.

isSimulationError()

Returns true if there was an error during the simulation, or false if there wasn’t.

getMetadata()

Returns an object with the network metadata:

{
  "name": "Magnetic Island",
  "id": "af70f5d8-7902-4803-8b49-3cfa50a9823e"
}

getUnits()

Returns a Units object with the units used in the network.

getTime()

Returns a Time object representing the current time in the simulation. The timezone property is the timezone of the actual network, so for Magnetic Island, it’s Australia/Brisbane.

getStartTime()

Returns a Time object representing the start time of the simulation.

getNeighborAssets()

Returns an array of all the assets that are directly connected to the asset with the given ID.

Method signature

getNeighborAssets(assetId: string) : Asset[]

If you want to filter the returned assets, it’s better to use the getConnectedAssets method.

For example, in Magnetic Island, if you call the getNeighborAssets method on the “Nellybay” tank, you will get an array of all the pipes that are connected to it (5 in this case):

const neighborAssets = network.getNeighborAssets('Nellybay')
console.log(neighborAssets.length) // 5

getConnectedAssets()

Returns an array of assets that are connected (i.e: can be reached traversing the network) to the given assets, and satisfy the given stop condition. The original assets are returned as well.

Method signature

getConnectedAssets(startIds: string[], stopCondition: function) : Asset[]

The stopCondition function is called for each asset that is connected to the assets with the given IDs. If the function returns true, the method will stop traversing the network and any subsequent assets will not be returned. If the function returns false, the method will continue traversing the network.

Examples

You can list all the assets that are reachable from an asset using a stopCondition function that always return false:

const reachableAssets = network.getConnectedAssets(['Nellybay'], () => false)
console.log(reachableAssets.length) // 3179

To retrieve all the valves that are reachable from the “Horseshoebay” tank in Magnetic Island:

const connectedAssets = network.getConnectedAssets(
  ['Horseshoebay'],
  (asset) => {
    return asset.type === 'Valve'
  }
)

getShortestPath()

Returns the shortest path between the given assets, and satisfies the given stop condition. The shortest path is the one that has the highest amount of connection weight.

Method signature

getShortestPath(fromId: string, toAsset: function, connectionWeight: function) : Asset[]

The toAsset function is called for each asset in the network. If the function returns true, the method will stop traversing the network and any subsequent assets will not be returned.

The connectionWeight function is called for each possible connection, with two parameters: the current asset that is being traversed, and the asset that is being evaluated. It should return a number representing the weight of the connection. If multiple connections are possible, higher weights are preferred. If the function returns the same number, the connection with the lowest ID is preferred. See the examples below for more details.

Example

To retrieve the shortest path between the “Nellybay” and the “Cocklebay” tanks in Magnetic Island. The weight of all connections is 1, so the path is the shortest.

const path = network.getShortestPath(
  'Nellybay',
  (asset) => asset.id === 'Cocklebay',
  (asset1, asset2) => 1
)

Find the path with the widest diameter pipes between the “Nellybay” and the “Cocklebay” tanks in Magnetic Island:

const widerPath = network.getShortestPath(
  'Nellybay',
  (asset) => asset.id === 'Cocklebay',
  (asset1, asset2) => {
    return asset1.diameter > asset2.diameter
  }
)

Find the path with the thinest diameter pipes between the “Nellybay” and the “Cocklebay” tanks in Magnetic Island. Note that this path is shorter than the previous one (37 vs 233 nodes).:

const widerPath = network.getShortestPath(
  'Nellybay',
  (asset) => asset.id === 'Cocklebay',
  (asset1, asset2) => {
    return asset1.diameter < asset2.diameter
  }
)

Network Manipulation

setDemand()

Sets the demand of a junction to the given value. Returns success if the demand was successfully set, or failure if the junction doesn’t exist or the demand could not be set.

Method signature

setDemand(junctionId: string, demand: number) : string

restoreDemand()

Method signature

Restores the demand of a junction to its default value. Returns success if the demand was successfully restored, or failure if the junction doesn’t exist or the demand could not be restored.

restoreDemand(junctionId: string) : string

setJunctionPressure()

Sets the residual pressure of a junction to the given value. Returns success if the residual pressure was successfully set, or failure if the junction doesn’t exist or the residual pressure could not be set.

Method signature

setJunctionPressure(junctionId: string, pressure: number) : string

restorePressure()

Method signature

Restores the residual pressure of a junction to its default value. Returns success if the residual pressure was successfully restored, or failure if the junction doesn’t exist or the residual pressure could not be restored.

restoreJunctionPressure(junctionId: string) : string

setSetting()

Sets the setting of a valve (the loss coefficient, in this case) to the given value. Returns success if the setting was successfully set, or failure if the valve doesn’t exist or the setting could not be set.

Method signature

setSetting(valveId: string, setting: number) : string

Example

network.setSetting('V_29279191', 0.5)

setStatus()

Sets the status of an asset to the given value. Returns success if the status was successfully set, or failure if the asset doesn’t exist or the status could not be set.

Method signature

setStatus(assetId: string, status: PipeStatus | PumpStatus | ValveStatus) : string

The different values for status are:

For Pipes:
- OPEN
- CLOSED
For Pumps:
- OPEN
- CLOSED
For Valves:
- OPEN
- CLOSED
- ACTIVE