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

TypeScript

import type { SDK } from '@qatium/sdk'
import type { Plugin } from '@qatium/sdk/plugin'

class MyPlugin implements Plugin {
  run() {
    const network = sdk.network;
  }
}

Python

from qatiumsdk import Plugin

class MyPlugin(Plugin):
  def run(self):
    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

TypeScript

getAsset<T extends Asset = Asset>(assetId: string) : T | undefined

Python

get_asset(asset_id: str) -> Optional[Asset]

Example

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

TypeScript

const tank = network.getAsset<Tank>('Horseshoebay')

Python

tank = network.get_asset('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

TypeScript

getAssets(filter?: function) : Asset[]

Python

get_assets(predicate: Optional[Callable[[Asset], bool]] = None) -> list[Asset]

Examples

Get all assets in Magnetic Island:

TypeScript

const allAssets = network.getAssets()

Python

all_assets = network.get_assets()

Get all assets in Magnetic Island that are tanks:

TypeScript

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

Python

tanks = network.get_assets(lambda 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

TypeScript

getJunctions(filter?: function) : Junction[]

Python

get_junctions(predicate: Optional[Callable[[Junction], bool]] = None) -> list[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.

TypeScript

getTanks(filter?: function) : Tank[]

Python

get_tanks(predicate: Optional[Callable[[Tank], bool]] = None) -> list[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

TypeScript

getPipes(filter?: function) : Pipe[]

Python

get_pipes(predicate: Optional[Callable[[Pipe], bool]] = None) -> list[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

TypeScript

getPumps(filter?: function) : Pump[]

Python

get_pumps(predicate: Optional[Callable[[Pump], bool]] = None) -> list[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.

TypeScript

getSupplySource(filter?: function) : SupplySource[]

Python

get_supply_sources(predicate: Optional[Callable[[SupplySource], bool]] = None) -> list[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.

TypeScript

getValves(filter?: function) : Valve[]

Python

get_valves(predicate: Optional[Callable[[Valve], bool]] = None) -> list[Valve]

Zone Queries

Note

The demo network, Magnetic Island, has no zones. To test these methods, make sure your network has at least one zone defined.

getZone()

Method signature

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

TypeScript

getZone(zoneId: string) : Zone | undefined

Python

get_zone(zone_id: str) -> Optional[Zone]

Example

TypeScript

const zone = network.getZone('Z1')

Python

zone = network.get_zone('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

TypeScript

getZones(filter?: function) : Zone[]

Python

get_zones(predicate: Optional[Callable[[Zone], bool]] = None) -> list[Zone]

Example

Get all zones in the network:

TypeScript

const allZones = network.getZones()

Python

all_zones = network.get_zones()

Get zones with ID Arcadia DMA or Horseshoe Bay DMA:

TypeScript

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

Python

zones = sdk.network.get_zones(lambda z: z.id == 'Arcadia DMA' or z.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.

Method signature

TypeScript

isScenarioActive(): boolean

Python

is_scenario_active() -> bool

isSimulationLoading()

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

Method signature

TypeScript

isSimulationLoading(): boolean

Python

is_simulation_loading() -> bool

isSimulationPeriodCompleted()

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

Method signature

TypeScript

isSimulationPeriodCompleted(): boolean

Python

is_simulation_period_completed() -> bool

isSimulationError()

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

Method signature

TypeScript

isSimulationError(): boolean

Python

is_simulation_error() -> bool

getMetadata()

Returns an object with the network metadata:

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

Method signature

TypeScript

getMetadata(): NetworkMetadata

Python

get_metadata() -> NetworkMetadata

getUnits()

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

getBounds()

Returns the bounds of the network.

TypeScript

type Bounds = {
  ne: { lng: number; lat: number };
  sw: { lng: number; lat: number };
};

Python

class Coordinate:
  lng: float
  lat: float

class Bounds:
  ne: Coordinate
  sw: Coordinate

Method signature

TypeScript

getBounds(): Bounds

Python

get_bounds() -> Bounds

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.

Method signature

TypeScript

getTime(): Time

Python

get_time() -> Time

getStartTime()

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

Method signature

TypeScript

getStartTime(): Time

Python

get_start_time() -> Time

getNeighborAssets()

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

Method signature

TypeScript

getNeighborAssets(assetId: string) : Asset[]

Python

get_neighbor_assets(asset_id: str) -> list[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):

TypeScript

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

Python

neighbor_assets = network.get_neighbor_assets('Nellybay')
print(len(neighbor_assets)) # 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

TypeScript

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

Python

get_connected_assets(start_ids: list[str], stop_condition: Callable[[Asset], bool]) -> list[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.

getConnectedAssets vs getNeighborAssets

The difference between getNeighborAssets and getConnectedAssets is that the latter can return any assets that are connected to the given assets, while the former returns only the direct neighbors.

See the next example, and compare the results with the getNeighborAssets example.

Examples

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

TypeScript

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

Python

reachable_assets = network.get_connected_assets(['Nellybay'], lambda: False)
print(len(reachable_assets)) # 3179

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

TypeScript

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

Python

connected_assets = network.get_connected_assets(
  ['Horseshoebay'],
  lambda: asset: 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[]

TypeScript

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

Python

get_shortest_path(from_id: str, to_asset: Callable[[Asset], bool], connection_weight: Callable[[Asset, Asset], float]) -> list[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.

TypeScript

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

Python

path = network.get_shortest_path(
  'Nellybay',
  lambda asset: asset.id == 'Cocklebay',
  lambda start, end: 1
)

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

TypeScript

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

Python

wider_path = network.get_shortest_path(
  'Nellybay',
  lambda asset: asset.id == 'Cocklebay',
  lambda start, end: start.diameter > end.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).:

TypeScript

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

Python

thinnest_path = network.get_shortest_path(
  'Nellybay',
  lambda asset: asset.id == 'Cocklebay',
  lambda start, end: start.diameter < end.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

TypeScript

setDemand(junctionId: string, demand: number, startDate?: Date) : string

Python

set_demand(junction_id: str, demand: float, start_date: Optional[datetime] = None) -> Union[Success, Failure]

Provided startDate will be automatically adjusted depending on the network configuration.

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.

TypeScript

restoreDemand(junctionId: string, startDate?: Date) : string

Python

restore_demand(junction_id: str, start_date: Optional[datetime] = None) -> Union[Success, Failure]

Provided startDate will be automatically adjusted depending on the network configuration.

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

TypeScript

setJunctionPressure(junctionId: string, pressure: number, startDate?: Date) : string

Python

set_junction_pressure(junction_id: str, pressure: float, start_date: Optional[datetime] = None) -> Union[Success, Failure]

Provided startDate will be automatically adjusted depending on the network configuration.

restoreJunctionPressure()

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.

TypeScript

restoreJunctionPressure(junctionId: string, startDate?: Date) : string

Python

restore_junction_pressure(junction_id: str, start_date: Optional[datetime] = None) -> Union[Success, Failure]

Provided startDate will be automatically adjusted depending on the network configuration.

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

TypeScript

setSetting(valveId: string, setting: number, startDate?: Date) : string

Python

set_setting(asset_id: str, setting: float, start_date: Optional[datetime] = None) -> Union[Success, Failure]:

Provided startDate will be automatically adjusted depending on the network configuration.

Example

TypeScript

network.setSetting('V_29279191', 0.5)

Python

network.set_setting('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

TypeScript

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

Python

set_status(asset_id: str, status: Literal['OPEN', 'CLOSED'], start_date: Optional[datetime] = None) -> Union[Success, Failure]:

The different values for status are:

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

Provided startDate will be automatically adjusted depending on the network configuration.

setTime()

Sets the network date and time to the non localized provided time.

Method signature

setTime(time: Date) : void

Example

TypeScript

network.setTime(new Date("2024-06-12T16:00:00Z" ))

Python

network.set_time(datetime(2024, 6, 12, 16, 0, 0))