Develop topology builder functionality

[networmix]

Add a functionality allowing to build networks out of a topology blueprint

Hierarchical “Blueprints”:

• Blueprints (or recipes) each define a self-contained sub-topology (e.g. a 3-tier Clos, Slim Fly, or other fabric).
• A top-level recipe instantiates these blueprints and interconnects them.

Groups and Adjacency:

• Within a blueprint, we declare node groups (e.g. leaf, spine) and specify connectivity with adjacency instructions (Mesh, Ladder, P2P, etc.).
• This structure makes it easy to define repeated or parametric topologies (like multiple leaves connecting to multiple spines).

Declarative YAML:

• Recipes should be written in YAML, making them readable, easily parameterizable, and compatible with the rest of NetGraph.

Maybe, should introduce a topology section into a scenario. This way the network will be an instantiation of a high-level topology description.

[networmix]

Thinking of something like this:

# Hierarchical DSL describing sub-topologies and multi-node expansions.
#
# Paths and Scopes:
# - Within a blueprint, a leading '/' (e.g., '/leaf') means "blueprint local root".
# - In the main network definition, a leading '/' (e.g., '/SFO') means "global root".
# - Omitting '/' means a relative path within the current scope (blueprint or network).
#
# Adjacency Patterns:
# - "mesh" cross-connects all nodes from source to all nodes from target, skipping self-loops.
# - "one_to_one" pairs up source[i] with target[i], also skipping self-loops.

blueprints:
  # A "blueprint" describes a reusable fragment of topology (e.g., a pattern).
  # It can be referenced in other blueprints or in the main 'network'.
  clos_2tier:
    groups:
      leaf:
        node_count: 4
        name_template: leaf-{node_num}
      spine:
        node_count: 4
        name_template: spine-{node_num}

    adjacency:
      - source: /leaf
        target: /spine
        pattern: mesh
        link_params:
          capacity: 100
          cost: 1000

  # Another blueprint referencing 'clos_2tier' as a sub-topology.
  city_cloud:
    groups:
      clos_instance:
        # Uses the 'clos_2tier' blueprint but overrides some parameters.
        use_blueprint: clos_2tier
        parameters:
          # Example override: more spine nodes and a new naming convention.
          spine.node_count: 6
          spine.name_template: "myspine-{node_num}"

      edge_nodes:
        node_count: 4
        name_template: edge-{node_num}

    adjacency:
      - source: /clos_instance/leaf
        target: /edge_nodes
        pattern: mesh
        link_params:
          capacity: 100
          cost: 1000

  # A minimal blueprint representing a single node.
  single_node:
    groups:
      single:
        node_count: 1
        name_template: single-{node_num}

# -- Main network definition --
network:
  name: "6-node-l3-us-backbone"
  version: 1.1

  groups:
    # 1) 'SEA' references the 'city_cloud' blueprint. This creates subgroups
    #    "SEA/clos_instance" and "SEA/edge_nodes" in the global scope.
    SEA:
      use_blueprint: city_cloud
      coords: [47.6062, -122.3321]

    # 2) 'SFO' references 'single_node' (one-node blueprint).
    SFO:
      use_blueprint: single_node
      coords: [37.7749, -122.4194]

  adjacency:
    # Each adjacency definition uses "mesh" in this scenario. Self-loops are automatically skipped.
    - source: /SFO
      target: /DEN
      pattern: mesh
      link_params:
        capacity: 100
        cost: 7754
        attrs:
          distance_km: 1550.77

    - source: /SFO
      target: /DFW
      pattern: mesh
      link_params:
        capacity: 200
        cost: 10000
        attrs:
          distance_km: 2000

    - source: /SEA/edge_nodes
      target: /DEN
      pattern: mesh
      link_params:
        capacity: 100
        cost: 6846
        attrs:
          distance_km: 1369.13

    - source: /SEA/edge_nodes
      target: /DFW
      pattern: mesh
      link_params:
        capacity: 100
        cost: 9600
        attrs:
          distance_km: 1920

  # Standalone nodes
  nodes:
    DEN:
      coords: [39.7392, -104.9903]
    DFW:
      coords: [32.8998, -97.0403]
    JFK:
      coords: [40.641766, -73.780968]
    DCA:
      coords: [38.907192, -77.036871]

  # Additional direct links
  # Note that each link references existing nodes (e.g., DEN, DFW).
  # If multiple links exist between the same two nodes, they have unique IDs
  # generated by the code, but share the same source/target.
  links:
    - source: DEN
      target: DFW
      link_params:
        capacity: 400
        cost: 7102
        attrs:
          distance_km: 1420.28
    - source: DEN
      target: DFW
      link_params:
        capacity: 400
        cost: 7102
        attrs:
          distance_km: 1420.28
    - source: DEN
      target: JFK
      link_params:
        capacity: 200
        cost: 7500
        attrs:
          distance_km: 1500
    - source: DFW
      target: DCA
      link_params:
        capacity: 200
        cost: 8000
        attrs:
          distance_km: 1600
    - source: DFW
      target: JFK
      link_params:
        capacity: 200
        cost: 9500
        attrs:
          distance_km: 1900
    - source: JFK
      target: DCA
      link_params:
        capacity: 100
        cost: 1714
        attrs:
          distance_km: 342.69

failure_policy:
  name: "anySingleLink"
  description: "Evaluate traffic routing under any single link failure."
  rules:
    - conditions:
        - attr: "type"
          operator: "=="
          value: "link"
      logic: "and"
      rule_type: "choice"
      count: 1

traffic_demands:
  - source: SEA
    target: JFK
    demand: 50
  - source: SFO
    target: DCA
    demand: 50
  - source: SEA
    target: DCA
    demand: 50
  - source: SFO
    target: JFK
    demand: 50

workflow:
  - step_type: BuildGraph
    name: build_graph