zepben.examples 0.2.0__py3-none-any.whl

zepben/examples/__init__.py

@@ -0,0 +1,5 @@
+#  Copyright 2022 Zeppelin Bend Pty Ltd
+#
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.

zepben/examples/building_network_hierarchy.py

@@ -0,0 +1,46 @@
+#  Copyright 2022 Zeppelin Bend Pty Ltd
+#
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from zepben.evolve import NetworkHierarchy, GeographicalRegion, SubGeographicalRegion, Feeder, Substation, Loop, Circuit
+
+# A network hierarchy describes the high-level hierarchy of the network.
+
+fdr1 = Feeder(name="Sydney feeder 1")
+fdr2 = Feeder(name="Sydney feeder 2")
+fdr3 = Feeder(name="Sydney feeder 3")
+fdr4 = Feeder(name="Newcastle feeder 1")
+fdr5 = Feeder(name="Newcastle feeder 2")
+fdr6 = Feeder(name="Newcastle feeder 3")
+
+sub1 = Substation(name="Sydney substation 1")
+sub2 = Substation(name="Sydney substation 2", normal_energized_feeders=[fdr1, fdr2, fdr3])
+sub3 = Substation(name="Newcastle substation", normal_energized_feeders=[fdr4, fdr5, fdr6])
+
+circuit_sydney = Circuit(end_substations=[sub1, sub2])
+loop_sydney = Loop(circuits=[circuit_sydney], substations=[sub1], energizing_substations=[sub2])
+sgr_sydney = SubGeographicalRegion(name="Sydney", substations=[sub1, sub2])
+sgr_newcastle = SubGeographicalRegion(name="Newcastle", substations=[sub3])
+
+gr_nsw = GeographicalRegion(name="New South Wales", sub_geographical_regions=[sgr_sydney, sgr_newcastle])
+
+network_hierarchy = NetworkHierarchy(
+    geographical_regions={gr_nsw.mrid: gr_nsw},
+    sub_geographical_regions={sgr.mrid: sgr for sgr in (sgr_sydney, sgr_newcastle)},
+    substations={sub.mrid for sub in (sub1, sub2, sub3)},
+    feeders={fdr.mrid: fdr for fdr in (fdr1, fdr2, fdr3, fdr4, fdr5, fdr6)},
+    circuits={circuit_sydney.mrid: circuit_sydney},
+    loops={loop_sydney.mrid: loop_sydney}
+)
+
+print("Network hierarchy:")
+for gr in network_hierarchy.geographical_regions.values():
+    print(f"- {gr.name}")
+    for sgr in gr.sub_geographical_regions:
+        print(f"  - {sgr.name}")
+        for sub in sgr.substations:
+            print(f"    - {sub.name}")
+            for fdr in sub.feeders:
+                print(f"      - {fdr.name}")

zepben/examples/connecting_to_grpc_service.py

@@ -0,0 +1,90 @@
+#  Copyright 2022 Zeppelin Bend Pty Ltd
+#
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import asyncio
+import json
+
+from zepben.auth import AuthMethod
+from zepben.evolve import connect_insecure, NetworkConsumerClient, connect_tls, connect_with_password, connect_with_secret, SyncNetworkConsumerClient, \
+    connect_with_token
+
+
+with open("config.json") as f:
+    c = json.loads(f.read())
+
+
+async def plaintext_connection():
+    """ Connects to an RPC server without TLS or authentication. This method should only be used in development and for demos. """
+    async with connect_insecure("hostname", 1234) as insecure_channel:
+        client = NetworkConsumerClient(insecure_channel)
+        grpc_result = await client.get_network_hierarchy()
+        print(grpc_result.result)
+
+
+async def secure_connection():
+    """ Connects to an RPC server over TLS. No user/client credentials are used. """
+    async with connect_tls("hostname", 1234) as secure_channel:
+        client = NetworkConsumerClient(secure_channel)
+        grpc_result = await client.get_network_hierarchy()
+        print(grpc_result.result)
+
+
+async def secure_connection_with_user_credentials():
+    """
+    Connects to an RPC server over TLS with user credentials. The authentication config will be fetched from
+    https://hostname/auth or https://hostname/ewb/auth by default, which includes the domain of the OAuth token provider.
+    """
+    async with connect_with_password("client ID", "username", "password", "hostname", 1234) as secure_channel:
+        client = NetworkConsumerClient(secure_channel)
+        grpc_result = await client.get_network_hierarchy()
+        print(grpc_result.result)
+
+    # Specify authentication config explicitly
+    async with connect_with_password("client ID", "username", "password", "hostname", 1234,
+                                     audience="https://fake_audience/", issuer_domain="fake.issuer.domain", auth_method=AuthMethod.AUTH0) as secure_channel:
+        client = NetworkConsumerClient(secure_channel)
+        grpc_result = await client.get_network_hierarchy()
+        print(grpc_result.result)
+
+
+async def secure_connection_with_client_credentials():
+    """
+    Connects to an RPC server over TLS with client credentials. The authentication config will be fetched from
+    https://hostname/auth or https://hostname/ewb/auth by default, which includes the domain of the OAuth token provider.
+    """
+    async with connect_with_secret("client ID", "client secret", "hostname", 1234) as secure_channel:
+        client = NetworkConsumerClient(secure_channel)
+        grpc_result = await client.get_network_hierarchy()
+        print(grpc_result.result)
+
+    # Specify authentication config explicitly
+    async with connect_with_secret("client ID", "client secret", "hostname", 1234,
+                                   audience="https://fake_audience/", issuer_domain="fake.issuer.domain", auth_method=AuthMethod.AUTH0) as secure_channel:
+        client = NetworkConsumerClient(secure_channel)
+        grpc_result = await client.get_network_hierarchy()
+        print(grpc_result.result)
+
+
+# You may use `SyncNetworkConsumerClient` if you prefer not to use asyncio.
+# The API calls are the same between `SyncNetworkConsumerClient` and `NetworkConsumerClient`.
+def connect_sync():
+    channel = connect_insecure("hostname", 1234)
+    client = SyncNetworkConsumerClient(channel)
+    grpc_result = client.get_network_hierarchy()
+    print(grpc_result.result)
+
+
+async def connect_using_token():
+    print("Connecting to EWB..")
+    channel = connect_with_token(host=c["host"], access_token=c["access_token"], rpc_port=c["rpc_port"])
+    client = NetworkConsumerClient(channel)
+    print("Connection established..")
+    print("Printing network hierarchy..")
+    grpc_result = await client.get_network_hierarchy()
+    print(grpc_result.result)
+
+
+if __name__ == "__main__":
+    asyncio.run(connect_using_token())

zepben/examples/current_state_manipulations.py

@@ -0,0 +1,265 @@
+#  Copyright 2023 Zeppelin Bend Pty Ltd
+#
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+import asyncio
+import sys
+from typing import List, Set
+
+from zepben.evolve import Feeder, PowerTransformer, Switch, assign_equipment_to_feeders, set_phases, NetworkConsumerClient, \
+    connect_with_password, BusbarSection, tracing, ConductingEquipment, ConductingEquipmentStep, Terminal, Breaker, EquipmentContainer
+
+"""
+Primary question to answer/example for:
+1. How to access the CIM model? Show examples of how the static/design and dynamic/current states of the network model is typically accessed by software
+ developers?
+    a. Can Zepben model be updated with dynamic ADMS state information
+    b. if we have current state of network (dynamically updated from ADMS), can we query the model to find all current connected HV feeders in a voltage bus?
+     (VVC Example)
+    c. How fast can we retrieve a model (dynamic sate) from CIM for near real time applications? (VVC Example)
+2. Show how the static and dynamic states of the network model is used by applications.
+"""
+
+
+async def run_simple(client: NetworkConsumerClient):
+    print()
+    print()
+    print("######################")
+    print("# FETCH ZONE FEEDERS #")
+    print("######################")
+    print()
+    print()
+    await fetch_zone_feeders(client)
+    print()
+    print()
+    print("##################")
+    print("# SPUR ISOLATION #")
+    print("##################")
+    print()
+    await isolate_spur_current(client)
+    print()
+    print()
+    print("##################")
+    print("# ZONE BUS TRACE #")
+    print("##################")
+    print()
+    await zone_bus_trace(client)
+    print()
+    print()
+
+
+async def fetch_zone_feeders(client: NetworkConsumerClient):
+    print("fetching network hierarchy...")
+    hierarchy = (await client.get_network_hierarchy()).throw_on_error().result
+    print("hierarchy fetched, fetching BAS feeders...")
+    substation = hierarchy.substations["BAS"]
+    for feeder in substation.feeders:
+        print(f"   {feeder.mrid}...")
+        await client.get_equipment_container(feeder.mrid, Feeder, include_energizing_containers=True, include_energized_containers=True)
+    print("CPM feeders fetched.")
+
+
+async def isolate_spur_current(client: NetworkConsumerClient):
+    feeder: Feeder = client.service.get("BAS022", Feeder)
+    switch: Switch = client.service.get("171143844", Switch)
+    tx: PowerTransformer = client.service.get("171143830", PowerTransformer)
+
+    log_spur("original:", switch, tx)
+
+    clear_feeders({feeder})
+
+    print(f"setting switch open...")
+
+    log_spur("cleaned:", switch, tx)
+
+    # Change the open state of the switch.
+    switch.set_open(True)
+
+    await recalculate_feeders({feeder})
+
+    log_spur("currently open:", switch, tx)
+
+
+def log_spur(desc: str, switch: Switch, tx: PowerTransformer):
+    print("==========================")
+    print(desc)
+    print(
+        f"   {str(switch)}: is_normally_open={switch.is_normally_open()}, "
+        f"is_open={switch.is_open()}, "
+        f"normal_feeders={[it.mrid for it in switch.normal_feeders]}, "
+        f"current_feeders={[it.mrid for it in switch.current_feeders]}"
+    )
+    print(
+        f"   {str(tx)}: nominal_phases={[it.phases.name for it in tx.terminals]}, "
+        f"normal_phases={[it.normal_phases.as_phase_code().name for it in tx.terminals]}, "
+        f"current_phases={[it.current_phases.as_phase_code().name for it in tx.terminals]}, "
+        f"normal_feeders={[it.mrid for it in tx.normal_feeders]}, "
+        f"current_feeders={[it.mrid for it in tx.current_feeders]}"
+    )
+    print("==========================")
+
+
+async def zone_bus_trace(client: NetworkConsumerClient):
+    feeder_head_terminals = [it.normal_head_terminal for it in client.service.objects(Feeder) if
+                             it.normal_head_terminal is not None and it.normal_head_terminal.conducting_equipment is not None]
+    feeder_heads = [it.conducting_equipment for it in feeder_head_terminals]
+    feeder_head_other_terms = [ot for it in feeder_head_terminals for ot in it.other_terminals()]
+
+    print(f"creating bus for {[feeder.mrid for it in feeder_heads for feeder in it.normal_feeders]}...")
+    # There is no subtrans in the model we pulled down so create a zone bus for all the feeders.
+    bus = BusbarSection()
+    bus_terminal = Terminal()
+    bus.add_terminal(bus_terminal)
+
+    for it in feeder_head_other_terms:
+        print(f"   connecting {[feeder.mrid for feeder in it.conducting_equipment.normal_feeders]} to bus...")
+        # disconnect the terminal from its energy source and move it to the bus
+        client.service.disconnect(it)
+        client.service.connect_terminals(bus_terminal, it)
+
+    print("bus created")
+    await log_bus("original:", bus, feeder_heads)
+
+    print("Setting BAS022 and BAS023 to currently open")
+    client.service.get("15416104", Breaker).set_open(True)  # BAS022 Breaker
+    client.service.get("15416128", Breaker).set_open(True)  # BAS023 Breaker
+
+    print("Setting BAS032 and BAS033 to normally open")
+    client.service.get("177750988", Breaker).set_normally_open(True)  # BAS032 Breaker
+    client.service.get("177750866", Breaker).set_normally_open(True)  # BAS033 Breaker
+
+    await log_bus("opened:", bus, feeder_heads)
+
+
+async def log_bus(desc: str, bus: ConductingEquipment, feeder_heads: List[ConductingEquipment]):
+    print("==========================")
+    print(desc)
+
+    # we run a trace on the assumption that the real model may have more equipment between the bus and the feeder heads.
+    # e.g. other minor busbars or ac line segments
+    trace = tracing.connected_equipment_trace()
+    open_heads: List[ConductingEquipment] = []
+    closed_heads: List[ConductingEquipment] = []
+    normally_open_heads: List[ConductingEquipment] = []
+    normally_closed_heads: List[ConductingEquipment] = []
+
+    # stop at all feeder heads
+    async def stop_on_feeder_heads(step: ConductingEquipmentStep) -> bool:
+        return isinstance(step.conducting_equipment, Switch) and step.conducting_equipment in feeder_heads
+
+    # stop at transformers to prevent tracing out of this zone into others
+    async def stop_on_transformers(step: ConductingEquipmentStep) -> bool:
+        return isinstance(step.conducting_equipment, PowerTransformer)
+
+    # sort feeder heads based on state
+    async def sort_feeder_heads(step: ConductingEquipmentStep):
+        if isinstance(step.conducting_equipment, Switch):
+            if step.conducting_equipment.is_open():
+                open_heads.append(step.conducting_equipment)
+            else:
+                closed_heads.append(step.conducting_equipment)
+            if step.conducting_equipment.is_normally_open():
+                normally_open_heads.append(step.conducting_equipment)
+            else:
+                normally_closed_heads.append(step.conducting_equipment)
+
+    trace.add_stop_condition(stop_on_feeder_heads)
+    trace.add_stop_condition(stop_on_transformers)
+    trace.if_stopping(sort_feeder_heads)
+
+    await trace.run_from(bus)
+    print(f"   disconnected feeders: {[feeder.mrid for it in open_heads for feeder in it.normal_feeders]}")
+    print(f"   connected feeders: {[feeder.mrid for it in closed_heads for feeder in it.normal_feeders]}")
+    print(f"   normally disconnected feeders: {[feeder.mrid for it in normally_open_heads for feeder in it.normal_feeders]}")
+    print(f"   normally connected feeders: {[feeder.mrid for it in normally_closed_heads for feeder in it.normal_feeders]}")
+    print("==========================")
+
+
+async def run_swap_feeder(client: NetworkConsumerClient):
+    open_point_id = "13953031"
+    isolation_point_id = "13952991"
+
+    # noinspection PyTypeChecker
+    open_point: Switch = (await client.get_identified_object(open_point_id)).throw_on_error().value
+    # noinspection PyTypeChecker
+    isolation_point: Switch = (await client.get_identified_object(isolation_point_id)).throw_on_error().value
+
+    feeder_ids = {it.to_mrid for it in client.service.get_unresolved_references_from(open_point.mrid) if it.resolver.to_class == EquipmentContainer}
+
+    # get the feeders on both sides of the open point.
+    print(f"fetching feeders...")
+    for feeder in feeder_ids:
+        print(f"   {feeder}...")
+        (await client.get_equipment_container(feeder)).throw_on_error()
+    print(f"done.")
+
+    feeders = set(open_point.normal_feeders)
+    log_txs(f"original:", feeders)
+
+    clear_feeders(feeders)
+
+    print(f"setting switches to move feeders...")
+
+    open_point.set_open(False)
+    isolation_point.set_open(True)
+
+    print(f"switches updated.")
+
+    await recalculate_feeders(feeders)
+
+    log_txs(f"swapped:", feeders)
+
+
+def clear_feeders(feeders: Set[Feeder]):
+    # remove the phases and feeders to show the difference in open/normal state
+    for feeder in feeders:
+        print(f"removing phases from {feeder.mrid}...")
+        # should use `await remove_phases().run(feeder.normal_head_terminal)`, but it is not working (or just really slow) for some reason...
+        for equip in feeder.equipment:
+            if isinstance(equip, ConductingEquipment):
+                for term in equip.terminals:
+                    term.normal_phases.phase_status = 0
+                    term.current_phases.phase_status = 0
+        print(f"phases removed, removing equipment...")
+        for equip in feeder.equipment:
+            equip.clear_containers()
+            equip.clear_current_containers()
+        feeder.clear_equipment()
+        feeder.clear_current_equipment()
+        print(f"equipment removed.")
+
+
+async def recalculate_feeders(feeders: Set[Feeder]):
+    # recalculate the phases and feeders with the new switch state.
+    for feeder in feeders:
+        print(f"assigning phases to {feeder.mrid}...")
+        await set_phases().run_with_terminal(feeder.normal_head_terminal)
+        print(f"phases assigned, assigning equipment...")
+        await assign_equipment_to_feeders().run_feeder(feeder)
+        print(f"equipment assigned.")
+
+
+def log_txs(desc: str, feeders: Set[Feeder]):
+    print()
+    print(desc)
+
+    for feeder in feeders:
+        print(f"   {feeder.mrid} txs: {sorted([tx.name for tx in feeder.current_equipment if isinstance(tx, PowerTransformer)])}")
+
+    print()
+
+
+async def main():
+    if len(sys.argv) != 6:
+        raise TypeError("you must provided the CLIENT_ID, username, password, host and port to connect")
+
+    # noinspection PyTypeChecker
+    async with connect_with_password(sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4], sys.argv[5]) as secure_channel:
+        await run_simple(NetworkConsumerClient(secure_channel))
+        await run_swap_feeder(NetworkConsumerClient(secure_channel))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

zepben/examples/examining_connectivity.py

@@ -0,0 +1,87 @@
+#  Copyright 2022 Zeppelin Bend Pty Ltd
+#
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+from zepben.evolve import EnergySource, AcLineSegment, Fuse, PowerTransformer, Breaker, EnergyConsumer, NetworkService, Terminal, connected_equipment, \
+    ConductingEquipment, PhaseCode, connected_terminals, ConnectivityResult
+
+# This example explores how to examine the immediate connectivity of equipment.
+# We will build a simple, linear network to examine:
+
+#    source     consumer
+#      |           |
+#     line       line
+#      |           |
+#     fuse      breaker
+#      |           |
+# transformer     fuse
+#      |           |
+#      +-----------+
+
+es_t = Terminal(mrid="es-t")
+es = EnergySource(mrid="es", terminals=[es_t])
+
+hv_line_t1, hv_line_t2 = Terminal(mrid="hv_line_t1"), Terminal(mrid="hv_line_t2")
+hv_line = AcLineSegment(mrid="hv_line", terminals=[hv_line_t1, hv_line_t2])
+
+hv_fuse_t1, hv_fuse_t2 = Terminal(mrid="hv_fuse_t1"), Terminal(mrid="hv_fuse_t2")
+hv_fuse = Fuse(mrid="hv_fuse", terminals=[hv_fuse_t1, hv_fuse_t2])
+
+tx_t1, tx_t2 = Terminal(mrid="tx_t1"), Terminal(mrid="tx_t2", phases=PhaseCode.ABCN)
+tx = PowerTransformer(mrid="tx", terminals=[tx_t1, tx_t2])
+
+lv_fuse_t1, lv_fuse_t2 = Terminal(mrid="lv_fuse_t1", phases=PhaseCode.ABCN), Terminal(mrid="lv_fuse_t2", phases=PhaseCode.ABCN)
+lv_fuse = Fuse(mrid="lv_fuse", terminals=[lv_fuse_t1, lv_fuse_t2])
+
+breaker_t1, breaker_t2 = Terminal(mrid="breaker_t1", phases=PhaseCode.ABCN), Terminal(mrid="breaker_t2", phases=PhaseCode.BN)
+breaker = Breaker(mrid="breaker", terminals=[breaker_t1, breaker_t2])
+
+lv_line_t1, lv_line_t2 = Terminal(mrid="lv_line_t1", phases=PhaseCode.BN), Terminal(mrid="lv_line_t2", phases=PhaseCode.BN)
+lv_line = AcLineSegment(mrid="lv_line", terminals=[lv_line_t1, lv_line_t2])
+
+ec_t = Terminal(mrid="ec_t", phases=PhaseCode.BN)
+ec = EnergyConsumer(mrid="ec", terminals=[ec_t])
+
+network = NetworkService()
+for io in [es_t, es, hv_line_t1, hv_line_t2, hv_line, hv_fuse_t1, hv_fuse_t2, hv_fuse, tx_t1, tx_t2, tx, lv_fuse_t1, lv_fuse_t2, lv_fuse, breaker_t1,
+           breaker_t2, breaker, lv_line_t1, lv_line_t2, lv_line, ec_t, ec]:
+    network.add(io)
+
+network.connect_terminals(es_t, hv_line_t1)
+network.connect_terminals(hv_line_t2, hv_fuse_t1)
+network.connect_terminals(hv_fuse_t2, tx_t1)
+network.connect_terminals(tx_t2, lv_fuse_t1)
+network.connect_terminals(lv_fuse_t2, breaker_t1)
+network.connect_terminals(breaker_t2, lv_line_t1)
+network.connect_terminals(lv_line_t2, ec_t)
+
+
+def fancy_print_connectivity_result(connectivity_result: ConnectivityResult):
+    print(f"\t{connectivity_result.from_terminal} to {connectivity_result.to_terminal}")
+
+    terminal_str_len = len(str(connectivity_result.from_terminal))
+    for core_path in connectivity_result.nominal_phase_paths:
+        print(f"\t{core_path.from_phase.name:>{terminal_str_len}}----{core_path.to_phase.name}")
+
+
+def fancy_print_connected_equipment(equipment: ConductingEquipment, phases=None):
+    if phases:
+        print(f"Connectivity results for {equipment} on phases {phases}:")
+    else:
+        print(f"Connectivity results for {equipment}:")
+    for connectivity_result in connected_equipment(equipment, phases):
+        fancy_print_connectivity_result(connectivity_result)
+    print()
+
+
+# connected_equipment(equipment, phases) will get all connections between equipment cores matching one of the requested phases.
+# The connected equipment does not need to connect via all specified phases to appear in the list of connectivity results.
+fancy_print_connected_equipment(tx)
+fancy_print_connected_equipment(tx, phases=PhaseCode.N)
+fancy_print_connected_equipment(breaker, phases=PhaseCode.BC)
+
+# connected_terminals is essentially connected_equipment where only one terminal is considered.
+print(f"Connectivity results for terminal {lv_fuse_t2} on phases {PhaseCode.ACN}:")
+for connectivity_result in connected_terminals(lv_fuse_t2, PhaseCode.ACN):
+    fancy_print_connectivity_result(connectivity_result)

zepben/examples/fetching_network_hierarchy.py

@@ -0,0 +1,36 @@
+#  Copyright 2023 Zeppelin Bend Pty Ltd
+#
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import asyncio
+import json
+
+from zepben.evolve import connect_with_token, NetworkConsumerClient
+
+with open("config.json") as f:
+    c = json.loads(f.read())
+
+
+async def main():
+    # See connecting_to_grpc_service.py for examples of each connect function
+    print("Connecting to EWB..")
+    channel = connect_with_token(host=c["host"], access_token=c["access_token"], rpc_port=c["rpc_port"])
+    client = NetworkConsumerClient(channel)
+    print("Connection established..")
+    # Fetch network hierarchy
+    network_hierarchy = await client.get_network_hierarchy()
+
+    print("Network hierarchy:")
+    for gr in network_hierarchy.result.geographical_regions.values():
+        print(f"- {gr.name}")
+        for sgr in gr.sub_geographical_regions:
+            print(f"  - {sgr.name}")
+            for sub in sgr.substations:
+                print(f"    - {sub.name}")
+                for fdr in sub.feeders:
+                    print(f"      - {fdr.name}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

zepben/examples/fetching_network_model.py

@@ -0,0 +1,88 @@
+#  Copyright 2022 Zeppelin Bend Pty Ltd
+#
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import asyncio
+import json
+
+from zepben.evolve import Conductor, PowerTransformer, ConductingEquipment, EnergyConsumer, Switch, \
+    connect_with_token, NetworkConsumerClient
+from zepben.protobuf.nc.nc_requests_pb2 import INCLUDE_ENERGIZED_LV_FEEDERS, INCLUDE_ENERGIZED_FEEDERS, INCLUDE_ENERGIZING_SUBSTATIONS, \
+    INCLUDE_ENERGIZING_FEEDERS
+
+with open("config.json") as f:
+    c = json.loads(f.read())
+
+
+async def main():
+    # See connecting_to_grpc_service.py for examples of each connect function
+    print("Connecting to EWB..")
+    channel = connect_with_token(host=c["host"], access_token=c["access_token"], rpc_port=c["rpc_port"])
+    feeder_mrid = "WD24"
+    print(f"Fetching {feeder_mrid}")
+    # Note you should create a new client for each Feeder you retrieve
+    # There is also a NetworkConsumerClient that is asyncio compatible, with the same API.
+    client = NetworkConsumerClient(channel=channel)
+    network = client.service
+
+    # Fetch feeder and all its LvFeeders
+    await client.get_equipment_container(feeder_mrid, include_energized_containers=INCLUDE_ENERGIZED_LV_FEEDERS)
+
+    print()
+    print(f"Total Number of objects: {client.service.len_of()}")
+    types = set(type(x) for x in network.objects(ConductingEquipment))
+    for t in types:
+        print(f"Number of {t.__name__}'s = {len(list(network.objects(t)))}")
+
+    total_length = 0
+    for conductor in network.objects(Conductor):
+        if conductor.length is not None:
+            total_length += conductor.length
+
+    print()
+    print(f"Total conductor length in {feeder_mrid}: {total_length:.3f}m")
+
+    print()
+    feeder = network.get(feeder_mrid)
+    print(f"{feeder.mrid} Transformers:")
+    for eq in feeder.equipment:
+        if isinstance(eq, PowerTransformer):
+            print(f"    {eq} - Vector Group: {eq.vector_group.short_name}, Function: {eq.function.short_name}")
+    print()
+
+    print()
+    print(f"{feeder_mrid} Energy Consumers:")
+    for ec in network.objects(EnergyConsumer):
+        print(f"    {ec} - Real power draw: {ec.q}W, Reactive power draw: {ec.p}VAr")
+    print()
+
+    print(f"{feeder_mrid} Switches:")
+    for switch in network.objects(Switch):
+        print(f"    {switch} - Open status: {switch.get_state():04b}")
+
+    # === Some other examples of fetching containers ===
+
+    # Fetch substation equipment and include equipment from HV/MV feeders powered by it
+    await client.get_equipment_container("substation ID", include_energized_containers=INCLUDE_ENERGIZED_FEEDERS)
+
+    # Same as above, but also fetch equipment from LV feeders powered by the HV/MV feeders
+    await client.get_equipment_container("substation ID", include_energized_containers=INCLUDE_ENERGIZED_LV_FEEDERS)
+
+    # Fetch feeder equipment without fetching any additional equipment from powering/powered containers
+    await client.get_equipment_container("feeder ID")
+
+    # Fetch HV/MV feeder equipment, the equipment from the substation powering it, and the equipment from the LV feeders it powers
+    await client.get_equipment_container("feeder ID",
+                                   include_energizing_containers=INCLUDE_ENERGIZING_SUBSTATIONS,
+                                   include_energized_containers=INCLUDE_ENERGIZED_LV_FEEDERS)
+
+    # Fetch LV feeder equipment and include equipment from HV/MV feeders powering it
+    await client.get_equipment_container("LV feeder ID", include_energizing_containers=INCLUDE_ENERGIZING_FEEDERS)
+
+    # Same as above, but also fetch equipment from the substations powering the HV/MV feeders
+    await client.get_equipment_container("LV feeder ID", include_energizing_containers=INCLUDE_ENERGIZING_SUBSTATIONS)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())