Datacenter Topology Generator

Generate datacenter network topologies from YAML, render condensed topology diagrams, and export a per-cable Excel cut-sheet.

The tool takes a topology config as input and produces:

• a topology diagram
• an Excel port mapping
• an Excel bill of materials
• a run log

Single-fabric runs write:

• topology.png
• port_mapping.xlsx
• bom.xlsx
• network_topology.log

Multi-fabric runs still write one port_mapping.xlsx and one bom.xlsx and one network_topology.log, but emit one diagram per fabric such as topology_backend.png.

CLI

The supported entrypoints are:

python -m topology_generator.main --config <config_path> --output-dir <output_dir>
python -m topology_generator --config <config_path> --output-dir <output_dir>
topology-generator --config <config_path> --output-dir <output_dir>

Add --timestamp to place the outputs in a timestamped subdirectory under the given output directory.

High-Level Model

The config defines an ordered list of layers and explicit links between adjacent layers.

• Single-fabric mode uses groups, layers, and links.
• Multi-fabric mode shares one gpu_nodes layer across multiple isolated fabrics via groupings, gpu_nodes, and fabrics.
• Port capacity is modeled in lane units through named port_pools, so one device can expose multiple independent lane budgets and mixed-speed modes.

Quick Start

Prerequisites

• Python 3.12+

Install

Runtime install:

make install

Development install:

make install-dev
pre-commit install

Run A Small Single-Fabric Example

python -m topology_generator.main \
  --config configs/examples/two_tier_small.yaml \
  --output-dir output/two_tier_small

Run A Small Multi-Fabric Example

python -m topology_generator.main \
  --config configs/examples/multi_fabric_small.yaml \
  --output-dir output/multi_fabric_small

For the full set of shipped examples and their expected outputs, see Worked Examples.

Configuration

The YAML stays intentionally explicit.

Single-fabric configs look like:

groups:
  - ...
layers:
  - ...
links:
  - ...

Multi-fabric configs look like:

groupings:
  - ...
gpu_nodes:
  total_nodes: ...
  fabric_port_pools:
    backend:
      - ...
fabrics:
  - ...

In multi-fabric mode, each fabric declares gpu_nodes_placement and each fabric-local layer uses a literal placement such as rack, pod, or global.

Every node-capable object now uses ordered port_pools, and every link names the pool it consumes via port_pool.

Use Configuration Reference for the canonical schema and validation rules.

Where To Go Next

• Configuration Reference: canonical config contract
• Architecture Overview: how the pipeline is structured
• Worked Examples: shipped example configs and expected results
• Contributing: developer workflow, validation, and profiling
• Agent Guide: repo-specific guidance for coding agents

License

MIT. See LICENSE.