VeraGridEngine.Devices.Diagrams package

Submodules

VeraGridEngine.Devices.Diagrams.base_diagram module

class VeraGridEngine.Devices.Diagrams.base_diagram.BaseDiagram(idtag: str | None, name: str, diagram_type: DiagramType = <enum 'DiagramType'>, use_flow_based_width: bool = False, min_branch_width: int = 1.0, max_branch_width=5, min_bus_width=1.0, max_bus_width=20, arrow_size=20, palette: Colormaps = VeraGrid, default_bus_voltage: float = 10)

Bases: object

Diagram

property arrow_size: float

Returns:

build_graph() → Tuple[nx.MultiDiGraph, List[Bus | FluidNode | Transformer3W | TransformerNW]]

Returns a networkx MultiDiGraph object of the grid. return MultiDiGraph, List[BusGraphicObject

copy(obj_dict: Dict[str, Dict[str, ALL_DEV_TYPES]] | None = None) → BaseDiagram

Copy the diagram layout while treating API objects as pointers.

Parameters:

obj_dict – Optional dictionary by device type and idtag used to rebind locations to objects in a target circuit.

Returns:

A copied diagram with detached layout containers.

property default_bus_voltage: float

Returns:

delete_device(device: ALL_DEV_TYPES) → object | None

Parameters:

device

Returns:

get_boundaries()

Get the graphic representation boundaries :return: min_x, max_x, min_y, max_y

get_data_dict() → Dict[str, str | int | float | Dict[str, GraphicLocation | MapLocation]]

get the properties dictionary to save :return: dictionary to serialize

property max_branch_width: float

Returns:

property max_bus_width: float

Returns:

property min_branch_width: float

Returns:

property min_bus_width: float

Returns:

property palette: Colormaps

Returns:

parse_data(data: Dict[str, Dict[str, Dict[str, int | float | bool | List[Tuple[float, float]]]]], obj_dict: Dict[str, Dict[str, ALL_DEV_TYPES]], logger: Logger)

Parse file data ito this class :param data: json dictionary :param obj_dict: dictionary of circuit objects by type to fincd the api objects back from file loading :param logger: logger

query_by_type(device_type: DeviceType) → PointsGroup | None

Query diagram by device type :param device_type: DeviceType :return: PointsGroup

query_point(device: ALL_DEV_TYPES) → GraphicLocation | MapLocation | None

Parameters:

device

Returns:

set_point(device: ALL_DEV_TYPES, location: GraphicLocation | MapLocation)

Parameters:

• device

• location

Returns:

set_size_constraints(use_flow_based_width: bool = False, min_branch_width: int = 5, max_branch_width=5, min_bus_width=20, max_bus_width=20, arrow_size=20)

Set the size constraints :param use_flow_based_width: :param min_branch_width: :param max_branch_width: :param min_bus_width: :param max_bus_width: :param arrow_size:

property use_api_colors: bool

property use_flow_based_width: bool

Returns:

class VeraGridEngine.Devices.Diagrams.base_diagram.PointsGroup(name: str = '')

Bases: object

Diagram

copy(obj_dict: Dict[str, ALL_DEV_TYPES] | None = None) → PointsGroup

Copy the locations while treating API objects as pointers.

If an object dictionary is supplied, locations are rebound to the matching object in that dictionary by idtag. Otherwise, the current API object pointer is preserved.

delete_device(device: ALL_DEV_TYPES)

Delete location :param device: :return:

get_dict() → Dict[str, GraphicLocation | MapLocation]

Returns:

parse_data(data: Dict[str, Dict[str, Any]], obj_dict: Dict[str, ALL_DEV_TYPES], logger: Logger, category: str = '') → None

Parse file data ito this class :param data: json dictionary :param obj_dict: dictionary of relevant objects (idtag, object) :param logger: Logger :param category: category

query_point(device: ALL_DEV_TYPES) → GraphicLocation | MapLocation | None

Parameters:

device

Returns:

set_point(device: ALL_DEV_TYPES, location: GraphicLocation | MapLocation)

Parameters:

• device

• location

Returns:

VeraGridEngine.Devices.Diagrams.base_diagram.add_branch_layout_edge(graph: nx.MultiDiGraph, from_idx: int, to_idx: int, branch: ALL_DEV_TYPES, dev_tpe: DeviceType, raw_impedance: float) → None

Add one branch edge with both physical distance and spring attraction metadata.

Parameters:

• graph – Diagram graph under construction.

• from_idx – Source node index.

• to_idx – Target node index.

• branch – Branch API object.

• dev_tpe – Branch device type.

• raw_impedance – Physical distance surrogate for impedance-aware layouts.

VeraGridEngine.Devices.Diagrams.base_diagram.add_node_layout_data(graph: nx.MultiDiGraph, node_index: int, api_object: ALL_DEV_TYPES) → None

Add one node together with the electrical metadata needed by the schematic layouts.

Parameters:

• graph – Diagram graph under construction.

• node_index – Integer node identifier.

• api_object – Diagram node API object.

VeraGridEngine.Devices.Diagrams.base_diagram.copy_diagrams(diagrams: List[BaseDiagram], obj_dict: Dict[str, Dict[str, ALL_DEV_TYPES]] | None = None) → List[BaseDiagram]

Copy diagrams while treating API objects as pointers.

Parameters:

• diagrams – Diagrams to copy.

• obj_dict – Optional target circuit object dictionary used to rebind pointers.

Returns:

Copied diagrams.

VeraGridEngine.Devices.Diagrams.base_diagram.get_branch_endpoint_voltages(branch: ALL_DEV_TYPES) → Tuple[float, float]

Get the endpoint voltages used to detect inter-level links.

Parameters:

branch – Branch API object.

Returns:

Pair of endpoint voltages in kV.

VeraGridEngine.Devices.Diagrams.base_diagram.get_layout_anchor(api_object: ALL_DEV_TYPES) → ALL_DEV_TYPES

Return the electrical anchor used to infer schematic layout metadata.

Parameters:

api_object – Diagram node API object.

Returns:

Anchor object carrying the electrical metadata for layout purposes.

VeraGridEngine.Devices.Diagrams.base_diagram.get_layout_is_dc(api_object: ALL_DEV_TYPES) → bool

Determine whether one diagram node belongs to the DC side of the network.

Parameters:

api_object – Diagram node API object.

Returns:

True when the node is DC.

VeraGridEngine.Devices.Diagrams.base_diagram.get_layout_is_slack(api_object: ALL_DEV_TYPES) → bool

Determine whether one diagram node should be treated as the island root candidate.

Parameters:

api_object – Diagram node API object.

Returns:

True when the node is electrically slack.

VeraGridEngine.Devices.Diagrams.base_diagram.get_layout_substation_name(api_object: ALL_DEV_TYPES) → str

Get the substation name used to stabilize the ordering inside one layer.

Parameters:

api_object – Diagram node API object.

Returns:

Substation name or an empty string.

VeraGridEngine.Devices.Diagrams.base_diagram.get_layout_voltage_kv(api_object: ALL_DEV_TYPES) → float

Get the voltage used to assign schematic layers.

Parameters:

api_object – Diagram node API object.

Returns:

Voltage in kV used by the automatic layout.

VeraGridEngine.Devices.Diagrams.block_diagram module

class VeraGridEngine.Devices.Diagrams.block_diagram.BlockDiagram

Bases: object

Diagram

add_branch(connectionitem_uid: int, device_uid_from: int, device_uid_to: int, port_number_from: int, port_number_to: int, color: str, elbow_points: List[Tuple[float, float]] = None)

Parameters:

• connectionitem_uid

• device_uid_from

• device_uid_to

• port_number_from

• port_number_to

• color

• elbow_points

Returns:

add_node(name: str, x: float, y: float, tpe: str, device_uid: int, api_object_name: str = '', state_ins: int = 0, state_outs: Sequence[str] | None = None, algeb_ins: int = 0, algeb_outs: Sequence[str] | None = None, color=None, subdiagram: BlockDiagram | None = None)

Parameters:

• api_object_name

• state_ins

• state_outs

• algeb_ins

• algeb_outs

• name

• x

• y

• device_uid

• tpe

• color

• subdiagram

Returns:

copy()

Deep copy of the block diagram :return:

empty() → bool

get_con_data_dict() → Dict[int, Dict[str, Any]]

Returns:

get_node_data_dict() → Dict[int, Dict[str, Any]]

Returns:

parse(data: Dict[str, Any])

Parameters:

data

Returns:

parse_branches(con_data) → None

Parse connection data from dictionary

parse_nodes(nodes_data) → None

Parse node data from dictionary

to_dict()

to dictionary function

class VeraGridEngine.Devices.Diagrams.block_diagram.BlockDiagramConnection

Bases: object

color: str

copy()

elbow_points: List[Tuple[float, float]] = None

from_uid: int

get_connection_dict()

get as a dictionary point :return:

port_number_from: int

port_number_to: int

to_uid: int

class VeraGridEngine.Devices.Diagrams.block_diagram.BlockDiagramNode

Bases: object

algeb_ins: int

algeb_outs: Sequence[str]

api_object_name: str

color: str

copy()

Deep copy :return:

device_uid: int

get_node_dict() → Dict[str, Any]

Returns:

name: str

state_ins: int

state_outs: Sequence[str]

sub_diagram: BlockDiagram = None

tpe: str

x: float

y: float

VeraGridEngine.Devices.Diagrams.graphic_location module

class VeraGridEngine.Devices.Diagrams.graphic_location.GraphicLocation

Bases: object

copy(api_object: ALL_DEV_TYPES | None = None) → GraphicLocation

Return a detached copy so diagrams do not accidentally share mutable layout state.

get_properties_dict() → Dict[str, Any]

get as a dictionary point :return:

VeraGridEngine.Devices.Diagrams.map_diagram module

class VeraGridEngine.Devices.Diagrams.map_diagram.MapDiagram

Bases: BaseDiagram

get_data_dict() → Dict[str, str | int | float | Dict[str, GraphicLocation | MapLocation]]

get the properties dictionary to save :return: dictionary to serialize

get_middle_coordinates() → Tuple[float, float]

Find the middle coordinates as diagram origin :return: Longitude and Latitude

parse_data(data: Dict[str, Dict[str, Dict[str, int | float]]], obj_dict: Dict[str, Dict[str, ALL_DEV_TYPES]], logger: Logger)

Parse file data ito this class :param data: json dictionary :param obj_dict: dictionary of circuit objects by type to fincd the api objects back from file loading :param logger: logger object

set_center() → None

Set the middle coordinates as diagram origin :return: Nothing

VeraGridEngine.Devices.Diagrams.map_location module

class VeraGridEngine.Devices.Diagrams.map_location.MapLocation(latitude: float = 0.0, longitude: float = 0.0, altitude: float = 0.0, api_object=None, draw_labels: bool = True)

Bases: object

GraphicLocation

property altitude

Returns:

copy(api_object=None) → MapLocation

Return a detached copy while preserving the API object as a pointer.

get_properties_dict() → Dict[str, float]

get as a dictionary point :return:

property latitude

Returns:

property longitude

Returns:

VeraGridEngine.Devices.Diagrams.palettes module

VeraGridEngine.Devices.Diagrams.palettes.blues_palette_bgr(x)

Blues palette :param x: [0, 1] :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.blues_palette_rgb(x)

Blues palette :param x: [0, 1] :return: RGB

VeraGridEngine.Devices.Diagrams.palettes.blues_to_gray_bgr(x)

Blue to gray :param x: [0, 1] :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.blues_to_gray_rgb(x)

Blues to gray palette :param x: [0, 1] :return: RGB

VeraGridEngine.Devices.Diagrams.palettes.green_to_red_bgr(x)

Green to red :param x: [-1, 1] :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.green_to_red_rgb(x)

Green to red palette :param x: [-1, 1] :return: RGB

VeraGridEngine.Devices.Diagrams.palettes.greens_palette_bgr(x)

Greens palette :param x: [0, 1] :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.greens_palette_rgb(x)

Greens palette :param x: [0, 1] :return: RGB

VeraGridEngine.Devices.Diagrams.palettes.heatmap_palette_bgr(x)

Heatmap colors :param x: [0, 1] :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.heatmap_palette_rgb(x)

Heatmap colors :param x: [0, 1] :return: RGB

VeraGridEngine.Devices.Diagrams.palettes.red_to_blue_bgr(x)

BGR Red to Blue :param x: [-1, 1] :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.red_to_blue_rgb(x)

BGR Red to Blue :param x: [-1, 1] :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.rgb2bgr(color)

VeraGridEngine.Devices.Diagrams.palettes.tso2_line_palette_bgr(x, warning_lvl=0.9, overload_lvl=1.15)

use TSO2 color scheme for people not to freak out Get RGB color from value :param x: value of loading in p.u. :param warning_lvl: Value of warning (i.e. 80%-> 0.8) :param overload_lvl: Value of overload (i.e. 110%-> 1.1) :return: BGR color

VeraGridEngine.Devices.Diagrams.palettes.tso_line_palette_bgr(v, loading, warning_lvl=0.9, overload_lvl=1.15)

Get the classic Substation colors :param v: line voltage in kV :param loading: loading in p.u. :param warning_lvl: Warning level :param overload_lvl: Overload level :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.tso_line_palette_rgb(x)

use Ree color scheme for people not to freak out :param x: [-1, 1] :return: RGB

VeraGridEngine.Devices.Diagrams.palettes.tso_substation_palette_bgr(x)

Get the classic Substation colors :param x: Substation voltage in kV :return: BGR

VeraGridEngine.Devices.Diagrams.palettes.tso_substation_palette_rgb(x)

Get the classic Substation colors :param x: Substation voltage in kV :return: RGB

VeraGridEngine.Devices.Diagrams.schematic_diagram module

class VeraGridEngine.Devices.Diagrams.schematic_diagram.SchematicDiagram(idtag=None, name='')

Bases: BaseDiagram

Diagram

copy_layout_state(source_api_object: ALL_DEV_TYPES, target_api_object: ALL_DEV_TYPES, include_geometry: bool = False) → GraphicLocation | None

Copy persisted schematic route and attachment state from one device to another.

get_attachment(api_object: ALL_DEV_TYPES, endpoint: str) → Dict[str, Any]

Return persisted attachment metadata for a branch endpoint or dockable child.

get_attachment_record(api_object: ALL_DEV_TYPES, endpoint: SchematicBranchEndpoint | str) → SchematicAttachmentRecord

Return one typed attachment record for runtime logic.

Parameters:

• api_object – Branch API object.

• endpoint – Runtime endpoint enum or persisted string.

Returns:

Typed attachment record.

get_branch_auto_route_style(api_object: ALL_DEV_TYPES) → SchematicAutoRouteStyle

Return the persisted automatic route style for one branch.

Parameters:

api_object – Branch API object.

Returns:

Branch-specific automatic route-style enum.

get_branch_route_points(api_object: ALL_DEV_TYPES) → List[Tuple[float, float]]

Return route points using the compatibility layer that understands both legacy and structured storage.

get_branch_route_record(api_object: ALL_DEV_TYPES) → SchematicRouteRecord | None

Return the typed route record for one branch.

Parameters:

api_object – Branch API object.

Returns:

Typed route record or None when no structured route has been stored.

get_dock(api_object: ALL_DEV_TYPES) → Dict[str, Any]

Return persisted dock metadata for a bus-connected child device.

get_dock_record(api_object: ALL_DEV_TYPES) → SchematicDockRecord

Return one typed dock record for runtime logic.

Parameters:

api_object – Injection API object.

Returns:

Typed dock record.

get_layout_metadata(api_object: ALL_DEV_TYPES) → Dict[str, Any]

Return a defensive copy of the persisted schematic layout metadata for this device.

set_attachment(api_object: ALL_DEV_TYPES, endpoint: str, attachment: Dict[str, Any]) → Dict[str, Any]

Persist attachment metadata through the compatibility layer.

set_attachment_record(api_object: ALL_DEV_TYPES, endpoint: SchematicBranchEndpoint | str, attachment_record: SchematicAttachmentRecord) → Dict[str, Any]

Persist one typed attachment record through the compatibility layer.

Parameters:

• api_object – Branch API object.

• endpoint – Runtime endpoint enum or persisted string.

• attachment_record – Typed attachment record.

Returns:

Updated layout metadata.

set_branch_auto_route_style(api_object: ALL_DEV_TYPES, route_style: SchematicAutoRouteStyle | str | None) → SchematicAutoRouteStyle

Persist the automatic route style for one branch.

Parameters:

• api_object – Branch API object.

• route_style – Requested route-style enum.

Returns:

Effective branch-specific route-style enum.

set_branch_route_points(api_object: ALL_DEV_TYPES, points: Iterable[Tuple[float, float]], kind: SchematicRouteKind | str | None = auto - polyline, locked: bool | None = False, route_style: SchematicAutoRouteStyle | str | None = None) → Dict[str, Any]

Persist route points through the compatibility layer while keeping legacy polyline storage in sync.

Parameters:

• api_object – Branch API object.

• points – Route points.

• kind – Route kind enum.

• locked – Locked-state flag.

• route_style – Automatic route-style enum.

Returns:

Updated layout metadata.

set_dock(api_object: ALL_DEV_TYPES, dock: Dict[str, Any]) → Dict[str, Any]

Persist dock metadata through the compatibility layer.

set_dock_record(api_object: ALL_DEV_TYPES, dock_record: SchematicDockRecord) → Dict[str, Any]

Persist one typed dock record through the compatibility layer.

Parameters:

• api_object – Injection API object.

• dock_record – Typed dock record.

Returns:

Updated layout metadata.

should_preserve_branch_route_shape(api_object: ALL_DEV_TYPES) → bool

Determine whether a branch should keep its persisted interior route elbows.

Parameters:

api_object – Branch API object.

Returns:

True when persisted route elbows should be preserved.

sync_attachment(api_object: ALL_DEV_TYPES, endpoint: SchematicBranchEndpoint | str, owner_device: ALL_DEV_TYPES | None) → Dict[str, Any]

Update endpoint ownership metadata while preserving any future slot-routing fields already stored.

sync_attachment_record(api_object: ALL_DEV_TYPES, endpoint: SchematicBranchEndpoint, owner_device: ALL_DEV_TYPES | None) → SchematicAttachmentRecord

Update one typed endpoint attachment record for runtime logic.

Parameters:

• api_object – Branch API object.

• endpoint – Typed branch endpoint.

• owner_device – Endpoint owner device.

Returns:

Typed attachment record.

sync_branch_attachment_records(api_object: ALL_DEV_TYPES) → Dict[SchematicBranchEndpoint, SchematicAttachmentRecord]

Synchronize the standard typed attachment records for branch-like devices.

Parameters:

api_object – Branch API object.

Returns:

Typed endpoint attachment records.

sync_branch_attachments(api_object: ALL_DEV_TYPES) → Dict[str, Dict[str, Any]]

Synchronize the standard ‘from’ and ‘to’ attachment ownership records for branch-like devices.

sync_branch_route_points(api_object: ALL_DEV_TYPES, points: Iterable[Tuple[float, float]]) → Dict[str, Any]

Update route points while preserving existing route kind and lock state.

sync_injection_dock(api_object: ALL_DEV_TYPES, owner_device: ALL_DEV_TYPES | None, side: SchematicAttachmentSide | str = bottom) → Dict[str, Any]

Synchronize dock metadata for a bus-connected child while preserving future docking fields.

sync_injection_dock_record(api_object: ALL_DEV_TYPES, owner_device: ALL_DEV_TYPES | None, side: SchematicAttachmentSide | str = bottom) → SchematicDockRecord

Synchronize one typed dock record for runtime logic.

Parameters:

• api_object – Injection API object.

• owner_device – Owning bus or fluid node.

• side – Typed default side.

Returns:

Typed dock record.

update_graphic_location(api_object: ALL_DEV_TYPES, x: float = 0.0, y: float = 0.0, w: float = 0.0, h: float = 0.0, r: float = 0.0, draw_labels: bool = True) → GraphicLocation

Update basic schematic geometry while preserving any route and attachment metadata already persisted.

update_xy(api_object: ALL_DEV_TYPES, x: int, y: int) → None

Update the element xy position :param api_object: Any DB object :param x: x position in px :param y: y position in px

upgrade_legacy_branch_layout(api_object: ALL_DEV_TYPES, start: Tuple[float, float], end: Tuple[float, float]) → Dict[str, Any]

Fill missing structured branch layout metadata for legacy diagrams.

VeraGridEngine.Devices.Diagrams.schematic_diagram.build_explicit_attachment_slot(owner_kind: SchematicAttachmentOwnerKind, side: SchematicAttachmentSide, order: int) → SchematicExplicitAttachmentSlot

Build one typed explicit attachment slot for runtime use.

Parameters:

• owner_kind – Typed owner kind.

• side – Typed attachment side.

• order – One-based slot order.

Returns:

Typed explicit attachment slot.

VeraGridEngine.Devices.Diagrams.schematic_diagram.get_attachment_owner_kind(owner_device: ALL_DEV_TYPES | None) → SchematicAttachmentOwnerKind | None

Map node device types to persisted attachment slot prefixes.

Parameters:

owner_device – Endpoint owner device.

Returns:

Typed slot prefix such as BUS or FLUID.

VeraGridEngine.Devices.Diagrams.schematic_diagram.get_default_attachment_side(owner_kind: SchematicAttachmentOwnerKind | None, endpoint: SchematicBranchEndpoint) → SchematicAttachmentSide

Choose the compatibility default side for one endpoint.

Parameters:

• owner_kind – Typed owner kind.

• endpoint – Typed branch endpoint.

Returns:

Typed compatibility side.

VeraGridEngine.Devices.Diagrams.schematic_diagram.get_side_from_slot_tuple(slot_tuple: Tuple[SchematicAttachmentOwnerKind, SchematicAttachmentSide, int] | None) → SchematicAttachmentSide | None

Convert one explicit slot tuple into a typed compatibility side.

Parameters:

slot_tuple – Parsed explicit slot tuple.

Returns:

Typed side when the tuple is present and valid.

VeraGridEngine.Devices.Diagrams.schematic_layout module

class VeraGridEngine.Devices.Diagrams.schematic_layout.SchematicAttachmentRecord

Bases: object

Store one typed attachment record for runtime behavior.

anchor_auto: bool

anchor_x: float | None

anchor_y: float | None

auto_slot: bool

explicit_slot: SchematicExplicitAttachmentSlot | None

explicit_terminal: SchematicExplicitAttachmentSlot | None

order: int | None

owner_device_id: str

owner_device_type: str

side: SchematicAttachmentSide | None

slot_side: SchematicAttachmentSide | None

terminal_side: SchematicAttachmentSide | None

class VeraGridEngine.Devices.Diagrams.schematic_layout.SchematicDockRecord

Bases: object

Store one typed dock record for runtime behavior.

offset: float

order: int | None

owner_device_id: str

owner_device_type: str

side: SchematicAttachmentSide | None

class VeraGridEngine.Devices.Diagrams.schematic_layout.SchematicExplicitAttachmentSlot(owner_kind: SchematicAttachmentOwnerKind, side: SchematicAttachmentSide, order: int)

Bases: object

Store one typed explicit attachment slot for runtime behavior.

order: int

owner_kind: SchematicAttachmentOwnerKind

side: SchematicAttachmentSide

class VeraGridEngine.Devices.Diagrams.schematic_layout.SchematicRouteRecord(points: List[Tuple[float, float]] | None = None, kind: SchematicRouteKind | None = None, locked: bool = False, route_style: SchematicAutoRouteStyle | None = None)

Bases: object

Store one typed route record for runtime behavior.

kind: SchematicRouteKind | None

locked: bool

points: List[Tuple[float, float]]

route_style: SchematicAutoRouteStyle | None

VeraGridEngine.Devices.Diagrams.schematic_layout.build_default_branch_route(start: Tuple[float, float], end: Tuple[float, float], start_order: int | None = None, end_order: int | None = None, route_style: SchematicAutoRouteStyle | str | None = straight) → List[Tuple[float, float]]

Build one deterministic coordinate-driven auto route.

Parameters:

• start – Start point.

• end – End point.

• start_order – Optional ordering hint used to separate coincident routes.

• end_order – Optional ordering hint used to separate coincident routes.

• route_style – Auto-route visual style.

Returns:

Route points.

VeraGridEngine.Devices.Diagrams.schematic_layout.build_explicit_attachment_slot_key(owner_kind: SchematicAttachmentOwnerKind | str, side: SchematicAttachmentSide | str, order: int) → str

Build a stable explicit slot identifier for persisted schematic attachments.

Parameters:

• owner_kind – Node kind prefix such as "bus" or "fluid".

• side – Attachment side.

• order – One-based slot order on that side.

Returns:

Explicit slot key.

VeraGridEngine.Devices.Diagrams.schematic_layout.build_route_stub_point(point: Tuple[float, float], side: str, stub_length: float) → Tuple[float, float]

Build the first orthogonal stub point that leaves a node from one side.

Parameters:

• point – Endpoint point.

• side – Attachment side.

• stub_length – Stub length.

Returns:

Stub point.

VeraGridEngine.Devices.Diagrams.schematic_layout.compress_route_points(points: Iterable[Tuple[float, float]]) → List[Tuple[float, float]]

Remove redundant route points while preserving orthogonal elbows.

Parameters:

points – Route points.

Returns:

Normalized route points without duplicates or collinear interior points.

VeraGridEngine.Devices.Diagrams.schematic_layout.copy_layout_metadata(location: GraphicLocation) → Dict[str, Any]

Return a defensive copy of the schematic metadata envelope.

VeraGridEngine.Devices.Diagrams.schematic_layout.ensure_layout_metadata(location: GraphicLocation) → Dict[str, Any]

Ensure the schematic metadata envelope exists and carries a schema version.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_attachment(location: GraphicLocation, endpoint: str) → Dict[str, Any]

Return attachment metadata for an endpoint such as ‘from’, ‘to’, or a shunt/injection id.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_attachment_record(location: GraphicLocation, endpoint: SchematicBranchEndpoint | str) → SchematicAttachmentRecord

Return one typed attachment record from persisted metadata.

Parameters:

• location – Graphic location record.

• endpoint – Runtime endpoint enum or persisted string.

Returns:

Typed attachment record.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_branch_route_points(location: GraphicLocation) → List[Tuple[float, float]]

Return branch route points, preferring structured route metadata but falling back to legacy polyline storage.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_branch_route_record(location: GraphicLocation) → SchematicRouteRecord | None

Return one typed route record from persisted metadata.

Parameters:

location – Graphic location record.

Returns:

Typed route record or None when the structured route section is absent.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_default_route_lane_index(start_order: int | None, end_order: int | None) → int

Build a deterministic lane index from endpoint slot orders.

Parameters:

• start_order – Start slot order.

• end_order – End slot order.

Returns:

One-based lane index.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_dock(location: GraphicLocation) → Dict[str, Any]

Return dock metadata for a bus-connected child such as a shunt or generator.

Parameters:

location – Graphic location record.

Returns:

Dock metadata dictionary.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_dock_record(location: GraphicLocation) → SchematicDockRecord

Return one typed dock record from persisted metadata.

Parameters:

location – Graphic location record.

Returns:

Typed dock record.

VeraGridEngine.Devices.Diagrams.schematic_layout.get_layout_section(location: GraphicLocation, section: str, default: Any = None) → Any

Return a copied layout metadata section so callers do not mutate persistence by accident.

VeraGridEngine.Devices.Diagrams.schematic_layout.is_axis_aligned_route_segment(start: Tuple[float, float], end: Tuple[float, float]) → bool

Determine whether one route segment is orthogonal.

Parameters:

• start – Segment start point.

• end – Segment end point.

Returns:

True when the segment is horizontal or vertical.

VeraGridEngine.Devices.Diagrams.schematic_layout.is_canonical_attachment_slot(slot_key: SchematicAttachmentSide | str | None) → bool

Determine whether a slot key is one of the compatibility aliases.

Parameters:

slot_key – Persisted slot key.

Returns:

True when the key is a compatibility alias or missing.

VeraGridEngine.Devices.Diagrams.schematic_layout.is_orthogonal_route(points: Iterable[Tuple[float, float]]) → bool

Determine whether a route is already orthogonal.

Parameters:

points – Route points.

Returns:

True when every segment is axis aligned.

VeraGridEngine.Devices.Diagrams.schematic_layout.parse_explicit_attachment_slot_key(slot_key: str | None) → Tuple[SchematicAttachmentOwnerKind, SchematicAttachmentSide, int] | None

Parse an explicit slot identifier.

Parameters:

slot_key – Persisted slot key.

Returns:

Tuple (owner_kind, side, order) or None when the key is not explicit.

VeraGridEngine.Devices.Diagrams.schematic_layout.parse_schematic_attachment_owner_kind(owner_kind: SchematicAttachmentOwnerKind | str | None) → SchematicAttachmentOwnerKind | None

Parse one attachment owner kind from runtime or persisted data.

Parameters:

owner_kind – Runtime enum or persisted string.

Returns:

Parsed owner kind enum or None when absent/unknown.

VeraGridEngine.Devices.Diagrams.schematic_layout.parse_schematic_attachment_side(side: SchematicAttachmentSide | str | None) → SchematicAttachmentSide | None

Parse one attachment side value from runtime or persisted data.

Parameters:

side – Runtime enum or persisted string.

Returns:

Parsed side enum or None when absent/unknown.

VeraGridEngine.Devices.Diagrams.schematic_layout.parse_schematic_auto_route_style(route_style: SchematicAutoRouteStyle | str | None) → SchematicAutoRouteStyle | None

Parse one auto-route style value from runtime or persisted data.

Parameters:

route_style – Runtime enum or persisted string.

Returns:

Parsed route-style enum or None when absent/unknown.

VeraGridEngine.Devices.Diagrams.schematic_layout.parse_schematic_branch_endpoint(endpoint: SchematicBranchEndpoint | str) → SchematicBranchEndpoint | None

Parse one branch endpoint value from runtime or persisted data.

Parameters:

endpoint – Runtime enum or persisted string.

Returns:

Parsed endpoint enum or None when absent/unknown.

VeraGridEngine.Devices.Diagrams.schematic_layout.parse_schematic_explicit_attachment_slot(slot_key: str | None) → SchematicExplicitAttachmentSlot | None

Parse one explicit persisted slot identifier into a typed runtime object.

Parameters:

slot_key – Persisted slot key.

Returns:

Typed explicit slot object or None when the key is not explicit.

VeraGridEngine.Devices.Diagrams.schematic_layout.parse_schematic_route_kind(kind: SchematicRouteKind | str | None) → SchematicRouteKind | None

Parse one route kind value from runtime or persisted data.

Parameters:

kind – Runtime enum or persisted string.

Returns:

Parsed route kind or None when absent/unknown.

VeraGridEngine.Devices.Diagrams.schematic_layout.serialize_schematic_attachment_side(side: SchematicAttachmentSide | str | None, default_side: SchematicAttachmentSide) → str

Serialize one attachment side to the persisted string representation.

Parameters:

• side – Runtime enum or persisted string.

• default_side – Default side when side is absent or invalid.

Returns:

Persisted side string.

VeraGridEngine.Devices.Diagrams.schematic_layout.serialize_schematic_auto_route_style(route_style: SchematicAutoRouteStyle | str | None, default_route_style: SchematicAutoRouteStyle) → str

Serialize one auto-route style to the persisted string representation.

Parameters:

• route_style – Runtime enum or persisted string.

• default_route_style – Default style when route_style is absent or invalid.

Returns:

Persisted route-style string.

VeraGridEngine.Devices.Diagrams.schematic_layout.serialize_schematic_explicit_attachment_slot(explicit_slot: SchematicExplicitAttachmentSlot) → str

Serialize one typed explicit slot to the persisted string representation.

Parameters:

explicit_slot – Typed explicit slot.

Returns:

Persisted slot key.

VeraGridEngine.Devices.Diagrams.schematic_layout.serialize_schematic_route_kind(kind: SchematicRouteKind | str | None, default_kind: SchematicRouteKind) → str

Serialize one route kind to the persisted string representation.

Parameters:

• kind – Runtime enum or persisted string.

• default_kind – Default route kind when kind is absent or invalid.

Returns:

Persisted route kind string.

VeraGridEngine.Devices.Diagrams.schematic_layout.set_attachment(location: GraphicLocation, endpoint: str, attachment: Dict[str, Any]) → Dict[str, Any]

Set attachment metadata for an endpoint.

VeraGridEngine.Devices.Diagrams.schematic_layout.set_attachment_record(location: GraphicLocation, endpoint: SchematicBranchEndpoint | str, attachment_record: SchematicAttachmentRecord) → Dict[str, Any]

Persist one typed attachment record while preserving the persisted schema.

Parameters:

• location – Graphic location record.

• endpoint – Runtime endpoint enum or persisted string.

• attachment_record – Typed attachment record.

Returns:

Updated layout metadata.

VeraGridEngine.Devices.Diagrams.schematic_layout.set_branch_route_points(location: GraphicLocation, points: Iterable[Tuple[float, float]], kind: SchematicRouteKind | str | None = auto - polyline, locked: bool | None = False, route_style: SchematicAutoRouteStyle | str | None = None) → Dict[str, Any]

Persist route points in both the legacy polyline field and the structured layout metadata.

Parameters:

• location – Graphic location record.

• points – Route points.

• kind – Route kind enum.

• locked – Locked-state flag.

• route_style – Automatic route-style enum.

Returns:

Updated layout metadata.

VeraGridEngine.Devices.Diagrams.schematic_layout.set_branch_route_record(location: GraphicLocation, route_record: SchematicRouteRecord) → Dict[str, Any]

Persist one typed route record while preserving the persisted schema.

Parameters:

• location – Graphic location record.

• route_record – Typed route record.

Returns:

Updated layout metadata.

VeraGridEngine.Devices.Diagrams.schematic_layout.set_dock(location: GraphicLocation, dock: Dict[str, Any]) → Dict[str, Any]

Set dock metadata for a bus-connected child.

Parameters:

• location – Graphic location record.

• dock – Dock metadata dictionary.

Returns:

Updated layout metadata.

VeraGridEngine.Devices.Diagrams.schematic_layout.set_dock_record(location: GraphicLocation, dock_record: SchematicDockRecord) → Dict[str, Any]

Persist one typed dock record while preserving the persisted schema.

Parameters:

• location – Graphic location record.

• dock_record – Typed dock record.

Returns:

Updated layout metadata.

VeraGridEngine.Devices.Diagrams.schematic_layout.set_layout_section(location: GraphicLocation, section: str, value: Any) → Dict[str, Any]

Replace a layout metadata section with a defensive copy.

VeraGridEngine.Devices.Diagrams.schematic_layout.should_preserve_route_shape(route: Dict[str, Any] | None) → bool

Determine whether one persisted route should drive redraw.

Locked routes always win. Non-locked auto-routed paths are regenerated from the current endpoint anchors, while manual polyline routes are kept exactly as saved apart from live endpoint replacement.

Parameters:

route – Persisted route metadata section.

Returns:

True when the interior route elbows should be preserved.

Module contents