Data Model

The Evolve SDK provides the building blocks you need to interface with the rest of the platform. It can also be used to build your own solutions from scratch that will be compatible with other things built with the SDK.

CIM Model

The EWB platform is composed around a domain model based on the 'Common Information Model' (CIM). The CIM is a very large standard that covers a huge amount of use cases. To make things more digestible, Zepben publishes its own CIM profile. CIM profiles are subsets of the whole CIM standard that dictates which parts of the model are in use. EWB publishes its model at https://zepben.github.io/evolve/docs/cim/evolve/.

If the EWB profile doesn't contain a part of CIM that you require for your use case, you can request or propose a change to the model by starting a discussion at the GitHub discussions or by contacting Zepben directly at https://www.zepben.com/contact.

Getting Started With The Model

tip

All things that have an ID in the CIM model inherit from IdentifiedObject. This provides common attributes such as mRID (master resource identifier), name, description, etc.

Let's get started with the data model by building the following contrived electrical circuit.

Here we simply have an AC energy source (EnergySource) connected to a conductor (ACLineSegment) connected to a circuit breaker (Breaker). In CIM all these things are a subtype of ConductingEquipment.

Let's see how we create them:

from zepben.evolve import EnergySource, AcLineSegment, Breaker

# Create the energy source. Providing no ID will generate a UUID.
source = EnergySource()

# Create the conductor providing a specific ID.
acls = AcLineSegment("aclineseg1")

# Create a circuit breaker.
# A UUID will be generated but we can give it a descriptive name.
breaker = Breaker(name="my circuit breaker")

Creating Connectivity

In CIM, all conducting equipment can have any number of Terminals, and terminals connect to other terminals using a ConnectivityNode. If we redraw the above diagram with all the required items from CIM it would look like:

Where the back dots represent the terminals and the black diamonds represent connectivity nodes.

Now, lets redo the above code sample this time also creating connectivity between the objects.

from zepben.evolve import EnergySource, AcLineSegment, Terminal, Breaker, ConnectivityNode

# Create the energy source
source = EnergySource()

# Create the terminal for the energy source and associate it with the source
source_t1 = Terminal(conducting_equipment=source)
source.add_terminal(source_t1)

# Create the conductor
acls = AcLineSegment()

# Create a terminal for each end of the conductor
# and associate them with the conductor
acls_t1 = Terminal(conducting_equipment=acls)
acls_t2 = Terminal(conducting_equipment=acls)
acls.add_terminal(acls_t1)
acls.add_terminal(acls_t2)

# Create a circuit breaker
breaker = Breaker()

# Create a terminal for the breaker
breaker_t1 = Terminal(conducting_equipment=breaker)

# Now create a connectivity node to connect the source terminal
# to the conductor's first terminal
cn1 = ConnectivityNode()

# Now associate the connectivity nodes to the terminals
cn1.add_terminal(source_t1)
source_t1.connectivity_node = cn1
cn1.add_terminal(acls_t1)
acls_t1.connectivity_node = cn1

# Now create a connectivity node to connect the source terminal
# to the conductor's first terminal
cn2 = ConnectivityNode()

# Now associate the connectivity nodes to the terminals
cn2.add_terminal(acls_t2)
acls_t2.connectivity_node = cn2
cn2.add_terminal(breaker_t1)
breaker_t1.connectivity_node = cn2

Normal and Current states

As the network is a dynamic model (that is things like switches can be open and closed), many things in the model support the notion of 'normal' and 'current'. For example, a switch has a normally open state and a currently open state. This allows you to perform analysis on the model considering the normal or current state of the network, and allows you to tell if the network is currently in the normal state or not. This can be important when making decisions based on analytics you may be running when using the model.

from zepben.evolve import Breaker

# Example of setting normal and current switch states
switch = Breaker()
switch.set_normally_open(True)
switch.set_open(False)

Phases

Phases in CIM are set on a Terminal. The phases property on the terminal should be considered as the terminal's 'nominal' phases. The vast majority of the time, this will be the actual active phases at that terminal. However, due to the dynamic nature of the network, it's possible that when tracing connecitvity that the active phase at the terminal is different. The phase can be tracked using the traced_phases property on the terminal.

tip

There are a number of helpful functions for tracing phases based on connectivity. See tracing for more details.

from zepben.evolve import Terminal, PhaseCode
# Example of setting nominal phases on a terminal
Terminal terminal = Terminal(phases=PhaseCode.ABC)

Grouping equipment

In electricity distribution networks, a model is typically made up of groups of equipment that represent different sections of the network. For example things like: feeder, zone (substation), transmission line etc. The terminology differs within the industry, however CIM provides types of EquipmentContainer to allow you to group equipment into the above types of categories. You can refer to the EWB CIM profile for all supported equipment container types in the model, however the most common ones are:

• Line
• Substation
• Feeder

We also extend CIM to provide an extension of the hierarchy to an LvFeeder, representing LV equipment underneath a distribution transformer.

Network Hierarchy

When creating a Substation you will see that it can belong to a SubGeographicalRegion and a SubGeogrpahicalRegion can belong to a GeographicalRegion.

When using various parts of the EWB platform, it will refer to the concept of a network hierarchy. This is the mechanism used to chunk up the network and provides an overview of what makes up the model. The network hierarchy looks as follows:

• GeographicalRegion
  • SubGeographicalRegion
    • Substation
      • Feeder
        • LvFeeder

When working with the EWB Platform, it is important to make sure equipment and equipment containers are correctly populated as there are assumptions built around the network being structured in this pattern.

Names and IDs

As everything in our model is ultimately an IdentifiedObject, it can have one or many "names" associated with it. The IdentifiedObject.name property is typically treated as a user-friendly name for a particular object. It is not a required field, and will default to an empty string if left unset. If set, it should be considered a presentation field for displaying in UI's or for providing context for an object. It should be avoided for storing any sort of information or metadata about an object beyond a human readable name.

Sometimes a need will arise to store extra IDs or metadata about a specific object alongside it's existing mRID and name. For example these could be IDs for separate systems (e.g GIS, DMS), or NMI's associated with the object. To store this information we recommend storing additional "names" via the IdentifiedObject.names field utilising NameTypes. Extra names are not considered presentation fields, and thus can have more structured string data within them.

To add extra names to an IdentifiedObject, utilise the addName function:

IdentifiedObject.add_name([str], [NameType]) The [str] represents the etra name given to the [IdentifiedObject] and [NameType] is the [NameType] object representing the type of this name.

Feeders

A feeder is generally a chain of equipment from a nominated starting point in a Substation to all open points when tracing along the equipment. The starting point can be defined by setting a Feeder's normal_head_terminal. This means if you have a correctly connected model, setting the feeder equipment container on any equipment can be calculated dynamically. This has the benefit of making sure that an equipment's feeder is always correct (because it has been set by checking connectivity). A function to do this is provided as part of the tracing package.

Example

The following example shows how you can build a network hierarchy and assign equipment to their appropriate equipment containers.

from zepben.evolve import GeographicalRegion, SubGeographicalRegion, PowerTransformer, Feeder, Breaker

region = GeographicalRegion()
sub_region = SubGeographicalRegion(geographical_region=region)
region.add_sub_geographical_region(sub_region)

substation = Substation(sub_geographical_region=sub_region)

sub_tx = PowerTransformer()
sub_tx.add_container(substation)
substation.add_equipment(sub_tx)

feeder = Feeder(normal_energizing_substation=substation)

feeder_cb = Breaker()
feeder_cb.add_container(feeder)
feeder.add_equipment(this)

---