layout-3 layout-6 layout-1 layout-top
layout-top layout-6 layout-1

Processing Engineering Diagrams into PDN Topology

Overview

This guide provides instructions for converting engineering one-line diagrams that show datacenter power connectivity into Power Distribution Network (PDN) topology that can be consumed by the Domain Power Service (DPS). One-line diagrams are standard electrical engineering drawings that illustrate the single-phase equivalent of a three-phase power system, showing all major components and their interconnections in a simplified, schematic format.

Alternative Approach: All manual topology entity creation and relationship definitions described in this guide can also be managed through the DPS user interface. For a graphical approach to topology management, see the Topology UI Guide.

Understanding One-Line Diagrams

What is a One-Line Diagram?

A one-line diagram (also called a single-line diagram) is a simplified notation for representing a three-phase power system. It shows:

  • Power Sources: Utility feeds, generators, UPS systems
  • Distribution Equipment: Transformers, switchgear, panels, PDUs
  • Protection Devices: Circuit breakers, fuses, disconnect switches
  • Load Equipment: Servers, networking equipment, storage systems
  • Power Flow Paths: How electricity flows from source to loads

Key Components in Datacenter One-Line Diagrams

  1. Utility Feed: Primary power source from the electrical grid
  2. Main Distribution Panels (MDP): High-voltage distribution points
  3. Transformers: Voltage step-down equipment
  4. Switchgear: Protection and switching equipment
  5. Floor PDUs: Building-level power distribution units
  6. Rack PDUs: Rack-level power distribution units
  7. Power Supply Units (PSUs): Server-level power conversion
  8. Compute Nodes: End-user equipment (servers, switches, storage)

DPS Topology Structure

Hierarchical Power Distribution Model

DPS models datacenter power infrastructure as a hierarchical tree structure where:

  • Root Nodes: Utility feeds or primary power sources (power domains)
  • Intermediate Nodes: Distribution equipment (transformers, PDUs, switchgear)
  • Leaf Nodes: End-consuming devices (compute nodes)

Entity Types in DPS

DPS is using DMTF/Redfish terminology and supports the following entity types for power infrastructure:

Entity Type Description Examples
PowerDomain Power domain Utility feed or any other resource, constrained or unconstrained
PowerDistribution Power distribution equipment Floor PDUs, Rack PDUs
PowerSupply Power conversion units Server PSUs, UPS systems
ComputerSystem Computing equipment Servers, workstations

Equipment Type Classification

PowerDistribution entities are further classified by EquipmentType:

  • FloorPDU: Building or floor-level power distribution
  • RackPDU: Rack-level power distribution

Step-by-Step Conversion Process

Step 1: Analyze the One-Line Diagram

  1. Identify Power Flow Direction: Start from utility feeds and trace power flow to end loads
  2. Catalog All Components: List every piece of equipment shown in the diagram
  3. Map Power-Relevant Connections: Document how components with power limits connect to others in the power distribution hierarchy
  4. Note Power Ratings: Record power limits (wattage) where specified

Step 2: Create Entity Inventory

Important: Not all components must be included. It makes sense to include components that have power limits, consume power, power management capabilities, or serve as power distribution points. Components that are purely electrical, do not have any power limits and do not support power management features can be omitted from the DPS topology.

Note: The examples used in this guide are simplified. Their purpose is to demonstrate how to create a functional topology file. In real-world scenarios, your topology will be significantly more complex with many more entities, detailed power specifications, and comprehensive relationship mappings.

For each power-relevant component in the diagram, collect the following information:

Required Information

  • Type: DPS entity type (PowerDomain, PowerDistribution, PowerSupply, ComputerSystem)
  • Name: Human readable unique identifier
  • Parent Connections: What power source feeds this component
  • Child Connections: What power loads this component feeds

Optional Information

  • Power Limit: Power limit of this component
  • Static Load: Fixed power consumption (in watts)
  • Model: DPS predefined device model identifier
  • Redfish Endpoint: BMC management interface (currently for specific NVIDIA compute nodes only)

Step 3: Build the Topology JSON Structure

Create a JSON file with the following structure:

{
  "Entities": [
    // Individual entity definitions
  ],
  "Topology": {
    "Name": "pdn",
    "Entities": [
      // Topology relationship definitions
    ]
  },
  "Policies": [
    // Parent-child relationships
  ]
}

Step 4: Map Components to DPS Entities

Power Domain

For utility feeds or primary power sources with constraints:

{
    "Type": "PowerDomain",
    "Name": "PD-A",
    "Constraints": {
        "PowerValue": {
            "Value": 10000,
            "Type": "W"
        }
    },
    "Redfish": {
        "@odata.type": "#PowerDomain.v1_2_2.PowerDomain",
        "@odata.id": "/PD-A",
        "Id": "PD-A"
    }
}

This entity defines power domain that is limited to 10,000 watts. Constraints node can be present in any entity type and it means that sum of the power consumption of its children should not go above that value.

Power Distribution Equipment

For floor PDUs, transformers, and switchgear:

{
    "Type": "PowerDistribution",
    "Model": "FloorPDU95",
    "Name": "PDU",
    "Redfish": {
        "@odata.type": "#PowerDistribution.v1_4_0.PowerDistribution",
        "@odata.id": "/PDU",
        "Id": "PDU",
        "EquipmentType": "FloorPDU"
    }
}

This entity defines one possible floor PDU for power distribution. In this case, FloorPDU95 represents standard device with 0.95 efficiency factor as defined in the DPS device registry. Device registry and defining custom devices are covered in Step 6: Add Custom Device Specifications.

Compute Nodes

For servers and workstations:

{
    "Type": "ComputerSystem",
    "Name": "NODE-GB200-1",
    "Model": "DGX_GB200",
    "Redfish": {
        "@odata.type": "#ComputerSystem.v1_23_0.ComputerSystem",
        "@odata.id": "/NODE-GB200-1",
        "Id": "NODE-GB200-1",
        "URL": "https://NODE-GB200-1",
        "SecretName": "NODE-GB200-1"
    }
}

This entity defines a compute node with specific management capabilities. The ComputerSystem type represents end-consuming devices in the power hierarchy. The DGX_GB200 model references a predefined device specification in the DPS device registry. Besides standard Redfish definitions, Redfish section includes management endpoint information - the URL specifies the BMC endpoint for power monitoring and control, while SecretName references stored authentication credentials. This allows DPS to actively manage and monitor the server’s power consumption and apply power policies directly to the hardware.

Step 5: Define Hierarchical Relationships

Establish the parent-child relationships that represent power flow:

"Topology": {
    "Name": "pdn",
    "Entities": [
        {
            "Name": "NODE-GB200-1",
            "Policy": "Low"
        },
        {
            "Name": "NODE-GB200-2",
            "Policy": "Low"
        },
        {
            "Name": "RPDU",
            "Children": [
                "NODE-GB200-1",
                "NODE-GB200-2"
            ]
        },
        {
            "Name": "PDU",
            "Children": [
                "RPDU"
            ]
        },
        {
            "Name": "PD-A",
            "Children": [
                "PDU"
            ]
        }
    ]
}

Each entity can have a default power policy that will be applied on topology activation, but only if the entity is backed by a device that supports power limiting and defines a corresponding DPS power plugin.

Note: Leaf nodes (nodes without children) must be listed as their own Entities entry.

Complete Topology Example

The following example demonstrates a complete topology JSON file that incorporates all the concepts covered in the previous steps. This example defines a simple power distribution hierarchy with:

  • One power domain (utility feed) limited to 10,000 watts
  • One floor PDU with 95% efficiency
  • One rack PDU capable of 57,500 watts
  • Two DGX GB200 compute nodes
{
    "Entities": [
        {
            "Type": "PowerDomain",
            "Name": "PD-A",
            "Constraints": {
                "PowerValue": {
                    "Value": 10000,
                    "Type": "W"
                }
            },
            "Redfish": {
                "@odata.type": "#PowerDomain.v1_2_2.PowerDomain",
                "@odata.id": "/PD-A",
                "Id": "PD-A"
            }
        },
        {
            "Type": "PowerDistribution",
            "Model": "FloorPDU95",
            "Name": "PDU",
            "Redfish": {
                "@odata.type": "#PowerDistribution.v1_4_0.PowerDistribution",
                "@odata.id": "/PDU",
                "Id": "PDU",
                "EquipmentType": "FloorPDU"
            }
        },
        {
            "Type": "PowerDistribution",
            "Model": "RackPDU95_57500W",
            "Name": "RPDU",
            "Redfish": {
                "@odata.type": "#PowerDistribution.v1_4_0.PowerDistribution",
                "@odata.id": "/RPDU",
                "Id": "RPDU",
                "EquipmentType": "RackPDU"
            }
        },
        {
            "Type": "ComputerSystem",
            "Name": "GB200-1",
            "Model": "DGX_GB200",
            "Redfish": {
                "@odata.type": "#ComputerSystem.v1_23_0.ComputerSystem",
                "@odata.id": "/GB200-1",
                "Id": "GB200-1",
                "URL": "https://GB200-1",
                "SecretName": "GB200-1"
            }
        },
        {
            "Type": "ComputerSystem",
            "Name": "GB200-2",
            "Model": "DGX_GB200",
            "Redfish": {
                "@odata.type": "#ComputerSystem.v1_23_0.ComputerSystem",
                "@odata.id": "/GB200-2",
                "Id": "GB200-2",
                "URL": "https://GB200-2",
                "SecretName": "GB200-2"
            }
        }
    ],
    "Topology": {
        "Name": "pdn",
        "Entities": [
            {
                "Name": "GB200-1",
                "Policy": "Low"
            },
            {
                "Name": "GB200-2",
                "Policy": "Low"
            },
            {
                "Name": "RPDU",
                "Children": [
                    "GB200-1",
                    "GB200-2"
                ]
            },
            {
                "Name": "PDU",
                "Children": [
                    "RPDU"
                ]
            },
            {
                "Name": "PD-A",
                "Children": [
                    "PDU"
                ]
            }
        ]
    },
    "Policies": [
        {
            "Name": "Low",
            "Limits": [
                {
                    "ElementType": "GPU",
                    "PowerLimit": {
                        "Percentage": 60
                    }
                },
                {
                    "ElementType": "CPU",
                    "PowerLimit": {
                        "Percentage": 60
                    }
                }
            ]
        },
        {
            "Name": "Medium",
            "Limits": [
                {
                    "ElementType": "GPU",
                    "PowerLimit": {
                        "Percentage": 80
                    }
                },
                {
                    "ElementType": "CPU",
                    "PowerLimit": {
                        "Percentage": 80
                    }
                }
            ]
        },
        {
            "Name": "High",
            "Limits": [
                {
                    "ElementType": "GPU",
                    "PowerLimit": {
                        "Percentage": 100
                    }
                },
                {
                    "ElementType": "CPU",
                    "PowerLimit": {
                        "Percentage": 100
                    }
                }
            ]
        }
    ]
}

Key Features of This Example

  1. Hierarchical Structure: Power flows from PD-A → PDU → RPDU → GB200 nodes
  2. Power Constraints: The power domain PD-A limits total consumption to 10,000 watts
  3. Device Models: Uses standard DPS device models (FloorPDU95, RackPDU95_57500W, DGX_GB200)
  4. Management Endpoints: Compute nodes include BMC URLs and authentication secrets
  5. Power Policies: Defines three power policies (Low, Medium, High) with different GPU/CPU limits
  6. Default Policy Assignment: Both compute nodes start with “Low” power policy

Note: The power policies shown in this example are simplified for demonstration purposes. For comprehensive information about policy design, configuration options, and best practices, refer to the Power Policies Guide.

Step 6: Add Custom Device Specifications (Optional)

Each topology entity can be backed by a device. Each device is represented by a unique string model and can be referenced in the topology definition using the Model parameter (as can be seen in the above examples). DPS embeds a standard devices.yaml file that contains predefined device specifications for common datacenter equipment. These standard devices are always available and cover most typical use cases, including NVIDIA DGX systems, standard PDUs, and common power distribution equipment. The latest devices.yaml file is included with the SDK as a reference.

However, if you need to define custom devices or override standard specifications, you can create your own device specification YAML file.

Standard Device Examples

Here are some examples from the standard devices.yaml that DPS provides:

ComputerSystem (DGX GB200):

- type: ComputerSystem
  description: NVIDIA GB200 Compute Tray (Bianca)
  model: DGX_GB200
  spec:
    devices:
      - type: CPU
        model: Grace
        count: 2
      - type: GPU
        model: GB200
        count: 4
    minLoadWatts: 900
    maxLoadWatts: 5640
    processorModulesCount: 2

PowerDistribution (Rack PDU):

- type: PowerDistribution
  description: Generic Rack PDU at 57500W 95 Pct Eff
  model: RackPDU95_57500W
  spec:
    maxLoadWatts: 57500
    efficiencyFactor: 0.95

GPU Component:

- type: GPU
  description: NVIDIA B200 GPU
  model: B200
  spec:
    minLoadWatts: 200
    maxLoadWatts: 1000
    wppsSupport: true

Field Explanations

  • type: DPS entity type (PowerDomain, PowerDistribution, PowerSupply, ComputerSystem, GPU, CPU)
  • description: Human-readable description of the device
  • model: Unique identifier used to reference this device specification
  • spec: Device-specific power and capability specifications
    • minLoadWatts/maxLoadWatts: Power consumption range in watts
    • efficiencyFactor: Power conversion efficiency (0.0-1.0)
    • devices: List of sub-components (for ComputerSystems)
    • wppsSupport: Whether device supports Workload Power Profile Settings
    • idlePolicy: Default power allocations for different component types
    • processorModulesCount: Number of processor modules (for specific systems)

Creating Custom Device Specifications

Important: When defining ComputerSystem devices, pay careful attention to the contained devices (CPU and GPU components). Each referenced device model in the devices list must also be defined in your device specifications file or available in the standard DPS device registry.

Create a YAML file with your custom device definitions:

# custom-devices.yaml
- type: ComputerSystem
  description: Custom Server Configuration
  model: CustomServer_8GPU
  spec:
    devices:
      - type: GPU
        model: CustomGPU
        count: 8
      - type: CPU
        model: CustomCPU
        count: 2
    minLoadWatts: 2000
    maxLoadWatts: 12000
    idlePolicy:
      Node:
        watts: 2000
      GPU:
        watts: 1500
      CPU:
        watts: 400
      Memory:
        watts: 100

- type: GPU
  description: Custom High-Performance GPU
  model: CustomGPU
  spec:
    minLoadWatts: 250
    maxLoadWatts: 800
    wppsSupport: true

- type: CPU
  description: Custom High-Performance CPU
  model: CustomCPU
  spec:
    minLoadWatts: 100
    maxLoadWatts: 400
    wppsSupport: true

Importing Custom Device Specifications

Use the DPS CLI to import your custom device specifications:

dpsctl device upsert custom-devices.yaml

Upsert Mode Behavior

Device specifications work in upsert mode, meaning:

  • New devices: Custom devices with unique model names are added to the registry
  • Override existing: If your custom device uses the same model name as a standard device, your specification will override the standard one
  • Merge capability: This allows you to customize standard devices for your specific environment while keeping other standard devices unchanged

This flexibility enables you to adapt DPS to your specific hardware configurations while leveraging the library of standard device specifications that DPS provides out of the box.

Best Practices and Guidelines

Component Selection Criteria

When converting engineering diagrams to DPS topology, include only components that:

  1. Have Power Management: Components with configurable power limits or power monitoring capabilities
  2. Consume Significant Power: Equipment with meaningful power consumption (typically >100W)
  3. Act as Distribution Points: Equipment that distributes power to multiple downstream devices
  4. Require Monitoring: Critical infrastructure components that need power oversight

Exclude purely electrical components like:

  • Circuit breakers and fuses (unless they have smart monitoring)
  • Manual disconnect switches
  • Basic electrical panels without power management
  • Passive electrical components (cables, connectors)

Naming Conventions

Consistent naming conventions are crucial for managing large-scale DPS topologies effectively. Well-structured entity names improve readability, simplify troubleshooting, and make topology maintenance much easier as your infrastructure grows. Consistent naming also helps administrators quickly understand the role and location of components when reviewing topology configurations or investigating power-related issues.

  1. Consistent Prefixes: You may use standard prefixes for component types

    • PDU- for floor PDUs
    • RPDU- for rack PDUs
    • NODE- for compute systems

  2. Location Encoding: You can include location information in names

    • PDU-A1- (Building A, Floor 1)
    • RPDU-A1-C19 (Building A, Floor 1, Cabinet 19)

Validation and Activation

Step 1: Schema Validation

Use DPS validation tools to check topology structure:

dpsctl topology validate --filename datacenter-topology.json

Note: Validation can be performed at any time and does not import the topology into DPS.

Step 2: Import Custom Device Specifications (if needed)

If you created custom device specifications, import them first:

dpsctl device upsert custom-devices.yaml

Step 3: Import Topology

Import the topology into DPS:

dpsctl topology import --filename datacenter-topology.json

Note: Topologies are uniquely identified by their name, and multiple topologies can be imported.

Step 4: Activate Topology

Activate the topology for power management:

dpsctl topology activate --topology pdn

Important: Only one topology can be active at a time, however, you may switch to a new topology using the --replace-topology flag.

Ongoing Management

After successfully activating your topology, ongoing management includes:

  1. Regular Updates: Update topology as infrastructure changes
  2. Capacity Monitoring: Monitor power utilization and plan for growth
  3. Policy Application: Apply appropriate power policies to different equipment types (see Power Policies Guide for detailed policy management)
  4. Performance Tuning: Optimize based on actual usage patterns

Example Workflow

Sample One-Line Diagram Conversion

Consider a simple datacenter with:

  • Utility feed → Main switchgear → 3 Floor PDUs → Rack PDUs → Compute nodes

The conversion process would be:

  1. Identify hierarchy levels: Utility → Floor PDUs → Rack PDUs → Nodes
  2. Create entity definitions for each piece of equipment
  3. Map relationships showing power flow from utility to compute nodes
  4. Add management endpoints for BMC-enabled devices
  5. Assign power ratings based on nameplate or measured data
  6. Validate, import and activate into DPS

This structured approach ensures that the engineering diagram is accurately represented as a DPS topology that can be used for comprehensive power management and optimization.

By following this guide, administrators can successfully convert engineering one-line diagrams into DPS topology configurations that enable effective datacenter power management and optimization.

    Copyright © 2025  NVIDIA Corporation