Presentations Guide

This guide explains the presentation system in PyPtP. Presentations are visual metadata that define how elements appear on schematic diagrams. They are required for network files to open in Gaia/Vision.

Full Example

View the complete code: 08_presentations_required.py

Why Presentations?

Presentations exist because PyPtP's file formats (GNF and VNF) were designed for Gaia and Vision, network analysis applications from Phase to Phase. These applications require schematic layout information alongside electrical data.

For purely programmatic use cases (data processing, calculations, or integration pipelines), we are exploring options to support networks without presentation data in future releases.

Why Presentations Matter

Networks must be valid both topologically (electrical connections) and schematically (visual layout) to function in Gaia/Vision. While presentations don't affect power flow calculations, they are mandatory for file validity.

Missing Presentations

Files without complete presentations will fail to open in Gaia/Vision, even if electrically correct.

What Presentations Are (and Aren't)

Presentations are visual metadata only. They tell Gaia/Vision where to draw elements on a schematic, but they don't alter the underlying network topology.

Common Misconception

Presentations cannot re-visualize your network's structure. If two nodes are connected by a cable, that connection exists regardless of how (or whether) you present it. Presentations let you:

• Show or hide elements on specific sheets
• Position elements at different coordinates
• Style symbols with colors and sizes

They do not let you:

• Display a simplified or alternative topology
• Visually "merge" or "split" nodes
• Show connections that don't exist electrically

Think of presentations as a layer of sticky notes on top of your network data. You can move the notes around, color them, or leave some out entirely. But rearranging notes doesn't change what's written underneath.

Presentation Types

Type	Used By	Purpose
NodePresentation	Nodes	Position of busbars, substations
BranchPresentation	Lines, cables, links	Path between two nodes
ElementPresentation	Sources, loads, generators	Position of attached elements

Sheet Requirement

Every network needs at least one sheet (the canvas where elements are drawn):

from pyptp import NetworkMV
from pyptp.elements.color_utils import CL_GRAY
from pyptp.elements.mv.sheet import SheetMV

network = NetworkMV()

sheet = SheetMV(SheetMV.General(name="Main", color=CL_GRAY))
sheet.register(network)
sheet_guid = sheet.general.guid

Node Presentations

Nodes require NodePresentation to specify their visual position:

from pyptp.elements.mv.node import NodeMV
from pyptp.elements.mv.presentations import NodePresentation

node = NodeMV(
    NodeMV.General(name="Substation", unom=10.0),
    presentations=[NodePresentation(sheet=sheet_guid, x=100, y=100)],
)
node.register(network)

NodePresentation Parameters

Parameter	Type	Required	Description
sheet	Guid	Yes	Sheet this presentation belongs to
x	int	Yes	Horizontal position (pixels)
y	int	Yes	Vertical position (pixels)
symbol	NodePresentationSymbol	No	Visual symbol type
size	int	No	Symbol size multiplier
color	int	No	Symbol color

Branch Presentations

Branches (lines, cables, links) require BranchPresentation to define the path between nodes:

from pyptp.elements.mv.link import LinkMV
from pyptp.elements.mv.presentations import BranchPresentation

link = LinkMV(
    LinkMV.General(node1=node1.general.guid, node2=node2.general.guid),
    presentations=[
        BranchPresentation(
            sheet=sheet_guid,
            first_corners=[(100, 100), (200, 100)],
            second_corners=[(300, 100)],
        )
    ],
)
link.register(network)

BranchPresentation Parameters

Parameter	Type	Required	Description
sheet	Guid	Yes	Sheet this presentation belongs to
first_corners	list[tuple]	Yes	Polyline from node1 outward
second_corners	list[tuple]	Yes	Polyline from node2 outward

See Branch Corners for detailed polyline routing.

Element Presentations

Elements attached to nodes (sources, loads, etc.) use ElementPresentation:

from pyptp.elements.mv.source import SourceMV
from pyptp.elements.mv.load import LoadMV
from pyptp.elements.mv.presentations import ElementPresentation

source = SourceMV(
    SourceMV.General(node=node1.general.guid, sk2nom=100.0),
    presentations=[ElementPresentation(sheet=sheet_guid, x=100, y=50)],
)
source.register(network)

load = LoadMV(
    LoadMV.General(node=node2.general.guid, P=50.0, Q=25.0),
    presentations=[ElementPresentation(sheet=sheet_guid, x=300, y=50)],
)
load.register(network)

ElementPresentation Parameters

Parameter	Type	Required	Description
sheet	Guid	Yes	Sheet this presentation belongs to
x	int	Yes	Horizontal position
y	int	Yes	Vertical position
symbol	int	No	Symbol type identifier
rotation	int	No	Symbol rotation (degrees)

Multiple Presentations

Elements can appear on multiple sheets. This is useful for:

• Overview diagrams showing the entire network
• Detail sheets focusing on specific feeders
• Different voltage level views

node = NodeMV(
    NodeMV.General(name="Busbar", unom=10.0),
    presentations=[
        NodePresentation(sheet=overview_guid, x=200, y=200),
        NodePresentation(sheet=detail_guid, x=100, y=150),
    ],
)

See Multi-Sheet Nodes for complete examples.

Complete Example

"""Presentations are required for all elements.

Networks must be valid both topologically and schematically to open in Gaia/Vision.
Presentations don't affect calculations but are mandatory for file validity.
"""

from pyptp import NetworkMV, configure_logging
from pyptp.elements.color_utils import CL_GRAY
from pyptp.elements.mv.link import LinkMV
from pyptp.elements.mv.load import LoadMV
from pyptp.elements.mv.node import NodeMV
from pyptp.elements.mv.presentations import BranchPresentation, ElementPresentation, NodePresentation
from pyptp.elements.mv.sheet import SheetMV
from pyptp.elements.mv.source import SourceMV
from pyptp.ptp_log import logger

configure_logging(level="INFO")

network = NetworkMV()

# Every network needs at least one sheet
sheet = SheetMV(SheetMV.General(name="Main", color=CL_GRAY))
sheet.register(network)
sheet_guid = sheet.general.guid

# Nodes require NodePresentation
node1 = NodeMV(
    NodeMV.General(name="Node1", unom=10.0),
    presentations=[NodePresentation(sheet=sheet_guid, x=100, y=100)],
)
node1.register(network)

node2 = NodeMV(
    NodeMV.General(name="Node2", unom=10.0),
    presentations=[NodePresentation(sheet=sheet_guid, x=300, y=100)],
)
node2.register(network)

# Branches require BranchPresentation
link = LinkMV(
    LinkMV.General(node1=node1.general.guid, node2=node2.general.guid),
    presentations=[
        BranchPresentation(
            sheet=sheet_guid,
            first_corners=[(100, 100), (200, 100)],
            second_corners=[(300, 100)],
        )
    ],
)
link.register(network)

# Elements require ElementPresentation
source = SourceMV(
    SourceMV.General(node=node1.general.guid, sk2nom=100.0),
    presentations=[ElementPresentation(sheet=sheet_guid, x=100, y=50)],
)
source.register(network)

load = LoadMV(
    LoadMV.General(node=node2.general.guid, P=50.0, Q=25.0),
    presentations=[ElementPresentation(sheet=sheet_guid, x=300, y=50)],
)
load.register(network)

network.save("with_presentations.vnf")
logger.info("Valid network saved")