Skip to main content
Version: 0.5.0

Requesting Models

danger

The API for consuming data from the Evolve data server is currently in alpha and very likely to experience breaking changes in the future. Please provide any feedback about this API to Zepben.

The SDK provides a client to request models to a remote data server via gRPC. The service and proto definitions for this API can be found here. An implementation of the consumer server is provided with the Evolve platform data services.

When working with models, it is often impractical to load a whole model to a client due to the size of the data. This is generally not a problem however, as most use cases only operate on a small subsection of the model at a time. So, the consumer API provides the ability to request smaller portions of the model quickly and easily. The other benefit to this is you can set up many clients in parallel operating on different chunks of the model to reduce the amount of time to run any analytics you may wish to perform across the whole model.

Connecting to a server​

TODO

Network Hierarchy​

The network can be built with a hierarchy as discussed earlier here. This allows you to easily identify and request smaller chunks of the network so you can focus on areas of concern. Here is an example of how to request the network hierarchy and print it out as a tree to the console.

void printNetworkHierarchy(NetworkConsumerClient client) {
    NetworkHierarchy hierarchy = client.getNetworkHierarchy().getResult();
    if (hierarchy == null)
        return;

    hierarchy.getGeographicalRegions().values().forEach(region -> {
        System.out.println(String.format("- %s [%s]", region.getName(), region.getMRID()));
        region.getSubGeographicalRegions().values().forEach(subRegion -> {
            System.out.println(String.format("  |- %s [%s]", subRegion.getName(), subRegion.getMRID()));
            subRegion.getSubstations().values().forEach(substation -> {
                System.out.println(String.format("    |- %s [%s]", substation.getName(), substation.getMRID()));
                substation.getFeeders().values().forEach(feeder -> {}
                    System.out.println(String.format("      |- %s [%s]", feeder.getName(), feeder.getMRID()));
                });
            });
        });
    });
}

Each item from the hierarchy result contains an identified object mRID and it's name. This simplified data structure enables you to do things like easily build a suitable UI component allowing a user to select a portion of the network they wish to use, without needing to pull back large amounts of full object data.

Requesting Identififed Objects​

Identified objects can be requested to build a model client side. When identified objects are loaded, any referenced objects that have not been previously requested need to be requested explicitly. The exception to this is terminals are always sent with their conducting equipment and transformer ends are always sent with transformers.

To find the mRIDs of any references that need to be requested you can use the deferred reference functions on the service provided when requesting identified objects.

void getWithBaseVoltage(NetworkService service, NetworkConsumerClient client, String mrid) {
    IdentifiedObject equipment = client.getIdentifiedObject(service, mrid).getResult();
    if (equipment == null || !(equipment instanceof ConductingEquipment)) {
        return;
    }
    
    Set<String> mrids = service.getUnresolvedReferenceMrids(Resolvers.baseVoltage(equipment));
    if (!mrids.isEmpty()) {
        client.getIdentifiedObject(service, mrids.iterator().next());
    }
}