v1.3.1

Breaking Changes

• None.

New Features

• None.

Enhancements

• None.

Fixes

• AcLineSegment.wire_info_for_phase will no longer throw an exception if an AcLineSegment has no phases specified.

Notes

• None.

v1.3.0

Breaking Changes

• Updated SetDirection to correctly use the @singledispatchmethod registration run instead of the old run_terminal. Simply replace your run_terminal
  call with run.
• EquipmentTreeBuilder.roots is now a dict keyed by the start_item rather than a Generator. This allows better lookup of root items when you are looking
  for an explicit items tree.
• Renamed PanDemandResponseFunction constructor argument appliances -> appliance to match the class property.
• Deprecated the following side-hustle shadowy names for PowerSystemResource.asset_info, just use asset_info directly:
  • Conductor.wire_info
  • CurrentTransformer.current_transformer_info
  • PotentialTransformer.potential_transformer_info
  • PowerTransformer.power_transformer_info
  • ProtectionRelayFunction.relay_info
  • ShuntCompensator.shunt_compensator_info
  • Switch.switch_info
• The ShuntCompensator.groundingTerminal must now:
  • Belong to the ShuntCompensator. Assigning a Terminal to ShuntCompensator.groundingTerminal will now set the terminals conductingEquipment to the
    ShuntCompensator if it isn't set, and throw an IllegalArgumentException if it is assigned to a different ConductingEquipment.
  • Be in the ShuntCompensator.terminals collection, and will be added automatically if it is missing on assignment, which in turn will update the
    sequenceNumber of the Terminal if it is 0.
  • Have phases N.
• Phase paths through a ShuntCompensator now add paths for mismatched phases between the grounding and normal terminals. This works in the same way as the
  PowerTransformer. This will only impact traces that are tracking the included phase paths, and will allow traces that previously stopped at the
  ShuntCompensator to continue. You should use the new stopOnShuntCompensatorGround condition to maintain current behaviour.
• NameType and Name now require constructor args to be supplied as kwargs only.
• GrpcClient now requires a stub to be passed into its constructor as a kw only arg.
• BaseService functions __contains__, get, add and remove have replaced their identified_object parameters with
  identifiable: Identifiable.
• BaseService members and functions that used to reference IdentifiedObject now use Identifiable instead.
• MultiObjectResult.objects is now a dict[str, Identifiable]. This will cause problems if you are explicitly expecting an IdentifiedObject to be
  returned via a consumer client call without any further type narrowing.
• Private function CimConsumerClient.extract_identified_objects has been renamed to extract_identifiables.
• ReferenceDifference members source and target_value now reference Identifiable.
• Renamed the following gRPC messages and attributes to support identifiable objects that don't descend from IdentifiedObject (such as DataSet):
  • In the cc protos:
    • CustomerConsumer.getIdentifiedObjects -> CustomerConsumer.getIdentifiables
    • GetIdentifiedObjectsRequest -> GetIdentifiablesRequest
    • GetIdentifiedObjectsResponse -> GetIdentifiablesResponse
    • GetIdentifiablesResponse.identified_objects -> GetIdentifiablesResponse.identifiables
    • CustomerIdentifiedObject -> CustomerIdentifiable
    • CustomerIdentifiable.identified_object -> CustomerIdentifiable.identifiable
    • GetCustomersForContainerResponse.identified_object -> GetCustomersForContainerResponse.identifiable
  • In the dc protos:
    • DiagramConsumer.getIdentifiedObjects -> DiagramConsumer.getIdentifiables
    • GetIdentifiedObjectsRequest -> GetIdentifiablesRequest
    • GetIdentifiedObjectsResponse -> GetIdentifiablesResponse
    • GetIdentifiablesResponse.identified_objects -> GetIdentifiablesResponse.identifiables
    • DiagramIdentifiedObject -> DiagramIdentifiable
    • DiagramIdentifiable.identified_object -> DiagramIdentifiable.identifiable
    • GetDiagramObjectsResponse.identified_object -> GetDiagramObjectsResponse.identifiable
  • In the nc protos:
    • NetworkConsumer.getIdentifiedObjects -> NetworkConsumer.getIdentifiables
    • GetIdentifiedObjectsRequest -> GetIdentifiablesRequest
    • GetIdentifiedObjectsResponse -> GetIdentifiablesResponse
    • GetIdentifiablesResponse.identified_objects -> GetIdentifiablesResponse.identifiables
    • NetworkIdentifiedObject -> NetworkIdentifiable
    • NetworkIdentifiable.identified_object -> NetworkIdentifiable.identifiable
    • GetEquipmentForContainersResponse.identified_object -> GetEquipmentForContainersResponse.identifiable
    • GetEquipmentForRestrictionResponse.identified_object -> GetEquipmentForRestrictionResponse.identifiable

New Features

• Added Conditions.stopOnShuntCompensatorGround, a new condition to prevent tracing through a ShuntCompensator using its grounding terminal.
• Added Identifiable interface which defines mrid.
• Anything implementing Identifiable can now be added to a BaseService.
• NameType and Name now implement Identifiable. Their mRID will be set to <name> and <name>-<type.name>-<identified_object.mrid>.
• Promoted BaseServiceReader, BaseServiceWriter, BaseCimReader, BaseCollectionReader, BaseCollectionWriter, and BaseServiceReader to the public API.
• Added customerIdentifiable to replace customer_identified_object with support for Identifiable object types in the future.
• Added diagramIdentifiable to replace diagram_identified_object with support for Identifiable object types in the future.
• Added networkIdentifiable to replace network_identified_object with support for Identifiable object types in the future.
• Added the following functions to all CimConsumerClient descendants:
  • get_identifiable which replaces the now deprecated get_identified_object.
  • get_identifiables which replaces the now deprecated get_identified_objects.

Enhancements

• Added sequence unpacking support for UnresolvedReference and ObjectDifference.
• SetDirection.run now supports ConductingEquipment.
• Fixed types on all overrides for PowerSystemResource.asset_info, removing the need to shadow them with type specific variants.
• You can now pass a list of TransformerEndRatedS to the PowerTransformerEnd constructor via the ratings argument.
• Updated all Callable type signatures for callables with unused return values to accept Any instead of None. The return is still unused, but requiring
  None raises types errors if anything is actually returned.
• IdentifiedObject, Name and NameType now extends Identifiable.
• BaseServiceComparator will now compare all Identifiable objects that have been added, not just IdentifiedObject objects.

Fixes

• Fixed the packing and unpacking of timestamps for Agreement.validity_interval in gRPC messages. Fix also ensures all other timestamps correctly support
  None when optional.
• Fixed an error in PhaseCode when adding NONE which previously resulted in NONE instead of the existing PhaseCode.
• BaseService.__contains__`` will now return falsewhen passed anIdentifiablethat is not in the service, instead of raising aKeyError`
• Clearing the names from an IdentifiedObject with no names no longer raises a TypeError.

Notes

• Deprecated the customer_identified_object function, please use the replacement customer_identifiable.
• Deprecated the diagram_identified_object function, please use the replacement diagram_identifiable.
• Deprecated the network_identified_object function, please use the replacement network_identifiable.
• Deprecated the following functions on all CimConsumerClient descendants:
  • get_identified_object which has been replaced with get_identifiable.
  • get_identified_objects which has been replaced with get_identifiables.

v1.2.0

Breaking Changes

• The following gRPC fields have been modified to support nulls (they were missed in v1.0.0):
  • Document.created_date_time
  • Equipment.commissioned_date
  • MeasurementValue.time_stamp
  • RelayInfo.curve_setting
  • RelayInfo.reclose_fast
• Removed TracedPhases. Terminal.normalPhases and Terminal.currentPhases should be used instead of Terminal.tracedPhases going forward. (missed in 0.48.0)

New Features

• Added the following new CIM classes:
  • DateTimeInterval, interval between two date and time points, where the interval includes the start time but excludes end time.
  • ElectronicAddress, electronic address information.
  • TelephoneNumber, telephone number.
  • HvCustomer - [ZBEX] an EquipmentContainer for high voltage customer assets.
  • LvSubstation - [ZBEX] an EquipmentContainer to represent distribution transformer sites, with associations to Feeder and LvFeeder
  • AcLineSegmentPhase - Details about an individual phase of an AcLineSegment.
• Added the following new CIM extension classes:
  • ContactDetails, the details required to contact a person or company. These can be accessed/used via a UsagePoint.
  • DirectionalCurrentRelay, a directional current relay is a type of protective relay used in electrical power systems to detect the direction of current
    flow and operate only when the current exceeds a certain threshold in a specified direction.
• Added new CIM extension enums:
  • ContactMethodType
  • PolarizingQuantityType
• Added new properties to the model:
  • PricingStructure.code - User allocated key for a pricing structure.
  • ShuntCompensator.grounding_terminal - [ZBEX] The terminal connecting to grounded network.
  • WireInfo - extra properties for conductors:
    • size_description
    • strand_count
    • core_strand_count
    • insulated
    • insulation_material
    • insulation_thickness
• Added new enum WireInsulationKind with extensions.
• Added helper function AcLineSegment.wire_info_for_phase() for retrieving the WireInfo for a given phase of a conductor.
• Added helper function EquipmentContainer.edge_terminals() for retrieving all terminals on the edge of an EquipmentContainer.
• Added support to filter NetworkHierarchy responses when calling NetworkConsumerClient.get_network_hierarchy(). A client can now choose what hierarchy
  containers should be populated in the response.
• Added AcLineSegment.wire_info_for_phase(phase: SinglePhaseKind) to retrieve the WireInfo associated with a given phase of a conductor.

Enhancements

• • BaseService.contains has been been expanded to support objects in addition to mRIDs.
• Agreement now supports validity_interval, the date and time interval the agreement is valid (from going into effect to termination).
• StreetDetail now supports extension building_number, the number of the building.
• TownDetail now supports country, the name of the country.
• ngen() now directly accepts dict()s and will return a generator of the values() or None if collection is None

Fixes

• Reordered the feeder equipment and direction assignment on database read to prevent parallel feeders from tracing back into the zone substation.
• NetworkDatabaseTables, CustomerDatabaseTables, DiagramDatabaseTables and BaseEntryWriter can now be imported from zepben.ewb and are officially
  regarded as public.

Notes

• None.

v1.1.0

Breaking Changes

• Updated EwbDataFilePaths to be an abstract class that supports variants. Added LocalEwbDataFilePaths which is a local file system implementation of
  EwbDataFilePaths, and should be used in place of the old EwbDataFilePaths.
• CopyableUUID has been removed, and replaced with a new generate_id function.
• All IdentifiedObject classes now require an mrid to be passed to the constructor, it will no longer be generated by default. This brings the Python SDK
  into alignment with the JVM SDK. You can use the new generate_id function if you can't provide a more meaningful mRID.

New Features

• None.

Enhancements

• Bumped hypothesis version for tests to latest (6.138.2), fixed examples generating large numbers of results causing tests to run extremely slow.
• Bumped every other dependency to the latest version aside from dataclassy.
• You can now opt out of the post read processing in the database readers using the optional preform_after_read_processing parameter.

Fixes

• Moved ZepbenTokenAuth to use python dataclasses instead of zepben.ewb.dataclassy, existing code should work as is.
• TypeErrors occurring in StepActions will no longer silently pass
• Drop python 3.9 from list of test envs in tox
• Fix an ImportError being raised when calling Conductor.is_underground()

Notes

• None.

v1.0.4

Breaking Changes

• None.

New Features

• None.

Enhancements

• None.

Fixes

• Fix an ImportError being raised when calling Conductor.is_underground()
• TypeErrors occurring in StepActions will no longer silently pass

Notes

• None.

v1.0.3

Fixes

• Moved ZepbenTokenAuth to use python dataclasses instead of zepben.ewb.dataclassy, existing code should work as is.

v1.0.0

Breaking Changes

• Removed support for Python 3.9. Upgrade your Python environment to at least 3.10.
• Renamed the package to zepben.ewb. You will need to update all your imports zepben.evolve.* -> zepben.ewb.*. This also updates the pypi artifact to
  zepben.ewb.
• Renamed length_from_t1_or_0 to length_from_t1_or_0.
• Relocated the following classes into the Zepben extensions area, marking them as [ZBEX]:
  • DistanceRelay: cim.iec61970.base.protection -> cim.extensions.iec61970.base.protection.
  • EvChargingUnit: cim.iec61970.infiec61970.wires.generation.production -> cim.extensions.iec61970.base.generation.production.
  • Loop: cim.iec61970.infiec61970.feeder -> cim.extensions.iec61970.base.feeder.
  • LvFeeder: cim.iec61970.infiec61970.feeder -> cim.extensions.iec61970.base.feeder.
  • PowerDirectionKind: cim.iec61970.infiec61970.protection -> cim.extensions.iec61970.base.protection.
  • ProtectionKind: cim.iec61970.infiec61970.protection -> cim.extensions.iec61970.base.protection.
  • ProtectionRelayFunction: cim.iec61970.base.protection -> cim.extensions.iec61970.base.protection.
  • ProtectionRelayScheme: cim.iec61970.base.protection -> cim.extensions.iec61970.base.protection.
  • ProtectionRelaySystem: cim.iec61970.base.protection -> cim.extensions.iec61970.base.protection.
  • RelayInfo: cim.iec61968.infiec61968.infassetinfo -> cim.extensions.iec61968.assetinfo.
  • RelaySetting: cim.iec61970.base.protection -> cim.extensions.iec61970.base.protection.
  • Site: cim.iec61970.base.core -> cim.extensions.iec61970.base.core.
  • TransformerCoolingType: cim.iec61970.base.wires -> cim.extensions.iec61970.base.wires.
  • TransformerEndRatedS: cim.iec61970.base.wires -> cim.extensions.iec61970.base.wires.
  • VectorGroup: cim.iec61970.base.wires -> cim.extensions.iec61970.base.wires.
  • VoltageRelay: cim.iec61970.base.protection -> cim.extensions.iec61970.base.protection.
  • WindingConnection: cim.iec61970.base.wires.winding -> cim.iec61970.base.wires.
• Relocated the following classes that were in the wrong packages:
  • Pole: cim.iec61968.assets -> cim.iec61968.infiec61968.infassets.
  • StreetlightLampKind: cim.iec61968.assets -> cim.iec61968.infiec61968.infassets.
  • All classes in the incorrectly located cim.iec61970.base.wires.generation.production -> cim.iec61970.base.generation.production.
• The protobuf implementation has the following changes, which will only have an impact if you are using protobuf directly:
  • Updated the values of the following enums to conform to Protobuf standard naming:
    • BatteryControlMode
    • BatteryStateKind
    • CustomerKind
    • DiagramStyle
    • EndDeviceFunctionKind
    • FeederDirection
    • IncludedEnergizedContainers
    • IncludedEnergizingContainers
    • LogLevel
    • LogSource
    • NetworkState
    • OrientationKind
    • PhaseCode
    • PhaseShuntConnectionKind
    • PotentialTransformerKind
    • PowerDirectionKind
    • ProtectionKind
    • RegulatingControlModeKind
    • SinglePhaseKind
    • StreetlightLampKind
    • SVCControlMode
    • SwitchAction
    • SynchronousMachineKind
    • TransformerConstructionKind
    • TransformerCoolingType
    • TransformerFunctionKind
    • UnitSymbol
    • VectorGroup
    • WindingConnection
    • WireMaterialKind
  • Renumbered the protobuf fields for:
    • AcLineSegment
    • Control
    • Diagram
    • TransformerEnd
• Renamed the following enum values:
  • PowerDirectionKind.UNKNOWN_DIRECTION -> PowerDirectionKind.UNKNOWN
  • RegulatingControlModeKind.UNKNOWN_CONTROL_MODE -> RegulatingControlModeKind.UNKNOWN
  • TransformerCoolingType.UNKNOWN_COOLING_TYPE -> TransformerCoolingType.UNKNOWN
  • WindingConnection.UNKNOWN_WINDING -> WindingConnection.UNKNOWN
• Added TransformerFunctionKind.UNKNOWN to allow distinction between an unknown function, and a function that is not covered by the enum (i.e. other). This
  addition has changed the order of the enum values, with other now being the last entry, instead of the first.
• NetworkConsumerClient and SyncNetworkConsumerClient no longer use the protobuf IncludedEnergizedContainers, IncludedEnergizingContainers and
  NetworkState enums directly, it now uses SDK versions of these enums. To use these enums you will need to update your imports, and use the simplified
  versions of the enum values:
  • IncludedEnergizedContainers from package zepben.ewb.streaming.get.
    • EXCLUDE_ENERGIZED_CONTAINERS -> NONE.
    • INCLUDE_ENERGIZED_FEEDERS -> FEEDERS.
    • INCLUDE_ENERGIZED_LV_FEEDERS -> LV_FEEDERS.
  • IncludedEnergizingContainers from package zepben.ewb.streaming.get.
    • EXCLUDE_ENERGIZING_CONTAINERS -> NONE.
    • INCLUDE_ENERGIZING_FEEDERS -> FEEDERS.
    • INCLUDE_ENERGIZING_SUBSTATIONS -> SUBSTATIONS.
  • NetworkState from package zepben.ewb.services.network.
    • ALL_NETWORK_STATE -> ALL.
    • NORMAL_NETWORK_STATE -> NORMAL.
    • CURRENT_NETWORK_STATE -> CURRENT.
• The zepben.auth dependency has been incorporated into the SDK with the following package change:
  • zepben.auth -> zepben.ewb.auth. You can also import these directly from zepben.ewb.
• SqliteTable now subclasses SqlTable.
• The following CIM fields have been made nullable. Note if previously accessing these fields you will now have to handle them potentially being null.
  • Analog.positiveFlowIn
  • Document.*
  • EnergyConsumer.grounded
  • EnergySource.isExternalGrid
  • IdentifiedObject.name
  • IdentifiedObject.description
  • IdentifiedObject.numDiagramObjects
  • Meter.companyMeterId
  • NameType.description
  • Pole.classification
  • PowerSystemResource.numControls
  • RegulatingCondEq.controlEnabled
  • ShuntCompensator.grounded
  • StreetAddress.postalCode
  • StreetAddress.poBox
  • StreetDetail.*
  • SynchronousMachine.earthing
  • TapChanger.controlEnabled
  • TransformerEnd.grounded
  • UsagePoint.isVirtual

New Features

• Created a new SqlTable that doesn't support creating schema creation statements by default.

Enhancements

• EquipmentTreeBuilder will now calculate leaves when specified to do so.

Fixes

• Marked some extensions properties and classes with [ZBEX] that were missing them (might still be more). In addition to the ones moved into the extensions
  package:
  • PhaseCode.Y
  • PhaseCode.YN
  • PowerElectronicsConnection.inverterStandard
  • PowerElectronicsConnection.sustainOpOvervoltLimit
  • PowerElectronicsConnection.stopAtOverFreq
  • PowerElectronicsConnection.stopAtUnderFreq
  • PowerElectronicsConnection.invVoltWattRespMode
  • PowerElectronicsConnection.invWattRespV1
  • PowerElectronicsConnection.invWattRespV2
  • PowerElectronicsConnection.invWattRespV3
  • PowerElectronicsConnection.invWattRespV4
  • PowerElectronicsConnection.invWattRespPAtV1
  • PowerElectronicsConnection.invWattRespPAtV2
  • PowerElectronicsConnection.invWattRespPAtV3
  • PowerElectronicsConnection.invWattRespPAtV4
  • PowerElectronicsConnection.invVoltVarRespMode
  • PowerElectronicsConnection.invVarRespV1
  • PowerElectronicsConnection.invVarRespV2
  • PowerElectronicsConnection.invVarRespV3
  • PowerElectronicsConnection.invVarRespV4
  • PowerElectronicsConnection.invVarRespQAtV1
  • PowerElectronicsConnection.invVarRespQAtV2
  • PowerElectronicsConnection.invVarRespQAtV3
  • PowerElectronicsConnection.invVarRespQAtV4
  • PowerElectronicsConnection.invReactivePowerMode
  • PowerElectronicsConnection.invFixReactivePower
  • PowerTransformerEnd.ratings
  • RegulatingControl.ratedCurrent
  • Sensor.relayFunctions
  • UsagePoint.approvedInverterCapacity
• using EquipmentTreeBuilder more then once per interpreter will no longer cause the roots to contain more objects then it should due to _roots being a
  class var
• Errors when initiating gRPC connections will now properly be propagated to users.

Notes

• None.

v0.48.0

Breaking Changes

• Updated to new Tracing API. All old traces will need to be re-written with the new API.
• AcLineSegment supports adding a maximum of 2 terminals. Mid-span terminals are no longer supported and models should migrate to using Clamp.
• Clamp supports only adding a single terminal.
• FeederDirectionStateOperations have been reworked to take NetworkStateOperators as a parameter.
• RemoveDirection has been removed. It did not work reliably with dual fed networks with loops. You now need to clear direction using the new ClearDirection
  and reapply directions where appropriate using SetDirection.
• Cut supports adding a maximum of 2 terminals.
• NetworkTraceTracker now uses a set to track visited objects, if you were using unhashable objects this will need to be addressed.
• Added a new debug_logging and name parameters to the constructor of the following traces. The helper functions in Tracing also have these parameters,
  which defaults to None and network_trace, meaning anyone using these wrappers will be unaffected by the change:
  • AssignToFeeders
  • AssignToLvFeeders
  • ClearDirection
  • FindSwerEquipment
  • PhaseInferrer
  • RemovePhases
  • SetDirection
  • SetPhases
• NetworkStateOperators has a new abstract description. If you are creating custom operators you will need to add it.
• StepAction will now raise an exception if apply is overridden. override _apply instead, or pass the function to __init__

New Features

• Added ClearDirection that clears feeder directions.
• You can now pass a logger to all Tracing methods and TestNetworkBuilder.build to enable debug logging for the traces it runs. The debug logging will
  include the results of all queue and stop condition checks, and each item that is stepped on.

Enhancements

• Tracing models with Cut and Clamp are now supported via the new tracing API.
• Added support to TestNetworkBuilder for:
  • with_clamp - Adds a clamp to the previously added AcLineSegment
  • with_cut - Adds a cut to the previously added AcLineSegment
  • connect_to - Connects the previously added item, rather than having to specify it again in connect.
  • You can now add sites to the TestNetworkBuilder via addSite.
  • You can now add busbar sections natively with from_busbar_section and to_busbar_section
  • The prefix for generated mRIDs for "other" equipment can be specified with the default_mrid_prefix argument in from_other and to_other.
• When processing feeder assignments, all LV feeders belonging to a dist substation site will now be considered energized when the site is energized by a
  feeder.
• NetworkTrace now supports starting from a known NetworkTraceStep.Path. This allows you to force a trace to start in a particular direction, or to continue
  a follow-up trace from a detected stop point.
• Traversal.is_stopping/Traversal.is_not_stopping now accept StepAction and any child classes, including those subclassing StepActionWithContextValue

Fixes

• When finding LvFeeders in the Site we will now exclude LvFeeders that start with an open Switch
• AssignToFeeder and AssignToLvFeeder will no longer trace from start terminals that belong to open switches
• The follow fixes were added to Traversal and NetworkTrace:
  • can_stop_on_start_item now works for branching traversals.
  • Traversal start items are added to the queue before traversal starts, so that the start items honour the queue type order.
  • Stop conditions on the NetworkTrace now are checked based on a step type, like QueueCondition does, rather than by checking can_action_item.
  • Cut and Clamp are now correctly supported in SetDirection and DirectionCondition.
  • NetworkTrace now handles starting on Cut , Clamp, and AcLineSegment and their terminals in a explicit / sensible way.
  • NetworkTracePathProvider now correctly handles next paths when starting on a Clamp terminal.
• NetworkTrace/Traversal now correctly respects can_stop_on_start_item when providing multiple start items.
• AssignToFeeders/AssignToLvFeeders now finds back-fed equipment correctly
• AssignToFeeders and AssignToLvFeeders will now associate PowerElectronicUnits with their powerElectronicsConnection Feeder/LvFeeder.
• Phases are now correctly assigned to the LV side of an LV2 transformer that is in parallel with a previously energised LV1 transformer.
• Added missing default network state operators (NORMAL) if you are calling SetDirection.run directly.

Notes

• None.

v0.47.1

Fixes

• Only resolve PowerSystemResource -> Asset relationship in one direction when calling get_equipment_container to stop deadlock.
• MultiObjectResult now exposes result types inheriting from IdentifiedObject to allow better type completion

v0.47.0

Fixes

• Downgrade protobuf and gRPC deps to fix SyncNetworkConsumerClient