YAML Configuration Guide

LaZagna uses YAML configuration files to define all parameters for 3D FPGA architecture generation and exploration. This guide covers every configuration option in detail, with examples.

Key Concepts

Defaults

Every parameter has a sensible default defined in setup_files/defaults.yaml. Your setup file is merged on top of the defaults — you only need to include what’s different.

The only required field is experiment_name.

Sweeping Parameters

Any parameter written as a list [] is automatically swept (Cartesian product with other swept parameters):

# Fixed — same value for every run:
placement:
  algorithm: "cube_bb"

# Swept — each value produces a separate run:
placement:
  algorithm: ["cube_bb", "per_layer_bb"]

Linked Parameters

Some parameters must vary together rather than as a Cartesian product:

architectures entries — each type + arch_file pair is one run
switch_block_3d.custom_patterns — each input + output pair is one run
switch_block_3d.location_pattern + grid_csv_path — each location + its CSV is one run
seeds — each seed is one run

Path Placeholders

Use {lazagna_root} to reference paths relative to the LaZagna installation directory:

benchmarks:
  directory: "{lazagna_root}/benchmarks/ITD_quick"

This resolves to the absolute path of your LaZagna install at runtime.

Quick Start

To run LaZagna with a configuration file:

python3 lazagna/main.py -f <path_to_setup_file>

Add -v for verbose output. See the setup_files/ directory for ready-to-use example configurations.

Minimal Setup File

experiment_name: "my_first_run"

This is a complete, valid setup file — everything else uses defaults (10×10 grid, combined architecture, and2_or2 benchmarks).

Configuration Sections

The YAML file is organized into hierarchical sections:

experiment_name          (required — unique name for this run)
├── grid                 (FPGA dimensions & channel width)
├── architectures        (architecture types to evaluate)
├── benchmarks           (benchmark circuits)
├── placement            (VPR placement algorithm)
├── seeds                (random seed configuration)
├── switch_block_3d      (3D switch block settings)
├── interlayer_delay      (vertical connection delay)
└── advanced             (extra VPR options)

Complete Reference

`experiment_name`


Required	✅ Yes
Type	string
Description	A unique name for this experiment. Used in output directory names.

experiment_name: "my_experiment"

`grid`

FPGA fabric dimensions and routing channel width.

Parameter	Type	Default	Description
`width_3d`	int	`10`	3D FPGA grid width (columns)
`height_3d`	int	`10`	3D FPGA grid height (rows)
`width_2d`	int	`15`	2D-equivalent grid width (used when architecture type is `2d`)
`height_2d`	int	`15`	2D-equivalent grid height
`channel_width`	int	`50`	Routing channel width

grid:
  width_3d: 25
  height_3d: 25
  width_2d: 35
  height_2d: 35
  channel_width: 100

Note

When the architecture type is 2d, the width_2d and height_2d values override width_3d and height_3d automatically. Typically the 2D grid is larger (two 3D layers flattened into one), but this is not enforced.

`architectures`

A list of FPGA architecture types to evaluate. Each entry is tested as a separate run (linked parameter).

Parameter	Type	Default	Description
`type`	string	`"combined"`	Architecture / switch-block type
`arch_file`	string	(auto)	Override the default architecture XML for this type

Available Types

Type	Description	Default Arch File
`combined`	3D SB with full vertical routing	`vtr_arch_dsp_bram.xml`
`3d_cb`	3D connection block only	`vtr_3d_cb_arch_dsp_bram.xml`
`3d_cb_out_only`	3D connection block (output only)	`vtr_3d_cb_out_only_arch_dsp_bram.xml`
`hybrid_cb`	Hybrid: CB + partial SB	`vtr_3d_cb_arch_dsp_bram.xml`
`hybrid_cb_out_only`	Hybrid: CB output + partial SB	`vtr_3d_cb_out_only_arch_dsp_bram.xml`
`2d`	2D baseline (no vertical connections)	`vtr_3d_cb_arch_dsp_bram.xml`

All default arch files are under arch_files/templates/dsp_bram/.

# Simple — use default arch file for one type:
architectures:
  - type: combined

# Sweep multiple architecture types:
architectures:
  - type: combined
  - type: 3d_cb
  - type: 2d

# Override an arch file for a specific type:
architectures:
  - type: combined
    arch_file: "{lazagna_root}/arch_files/my_custom_arch.xml"

Tip

You no longer need to remember arch file paths — just specify the type and the correct default file is chosen automatically. Use arch_file only when you have a custom architecture XML.

`benchmarks`

Which benchmark circuits to run through the FPGA flow.

Parameter	Type	Default	Description
`directory`	string	`"{lazagna_root}/benchmarks/and2_or2"`	Path to the benchmark directory
`is_verilog`	bool	`false`	`true` = Verilog (`.v`) benchmarks, `false` = BLIF (`.blif`) benchmarks

# BLIF benchmarks (MCNC-style):
benchmarks:
  directory: "{lazagna_root}/benchmarks/and2_or2"
  is_verilog: false

# Verilog benchmarks (Koios/ITD):
benchmarks:
  directory: "{lazagna_root}/benchmarks/ITD_quick"
  is_verilog: true

Note

For Verilog benchmarks, LaZagna will run Yosys for synthesis before VPR. Set is_verilog: true and point to a directory containing .v files.

`placement`

Controls the VPR placement algorithm.

Parameter	Type	Default	Description
`algorithm`	string or list	`["cube_bb"]`	Placement cost function. List = sweep.

Options: "cube_bb", "per_layer_bb"

# Single algorithm:
placement:
  algorithm: "cube_bb"

# Sweep two algorithms:
placement:
  algorithm: ["cube_bb", "per_layer_bb"]

`seeds`

Controls random seed behaviour for reproducibility.

Parameter	Type	Default	Description
`mode`	string	`"fixed"`	`"fixed"` = one deterministic seed; `"random"` = generate N random seeds
`value`	int	`1`	In fixed mode: the seed value. In random mode: number of seeds to generate.

# Deterministic single run:
seeds:
  mode: fixed
  value: 42

# 5 random seeds for statistical analysis:
seeds:
  mode: random
  value: 5

`switch_block_3d`

Configuration for 3D (vertical) switch blocks.

Parameter	Type	Default	Description
`connectivity`	float or list	`[1]`	Fraction of vertical connections (0–1). List = sweep.
`connection_type`	string or list	`["subset"]`	SB wiring pattern: `"subset"` or `"custom"`. List = sweep.
`switch_name`	string	`"3D_SB_switch"`	Name of the 3D SB switch in the architecture XML
`segment_name`	string	`"3D_SB_connection"`	Name of the 3D SB routing segment in the architecture XML
`input_pattern`	list of int	`[]`	Custom input turn pattern `[N, E, S, W]` (used with `connection_type: custom`)
`output_pattern`	list of int	`[]`	Custom output turn pattern `[N, E, S, W]`
`location_pattern`	string or list	`["repeated_interval"]`	Where to place 3D SBs
`grid_csv_path`	string or list	`""`	CSV file(s) for custom SB placement (required with `location_pattern: "custom"`)
`custom_patterns`	list	(none)	Multiple input/output patterns to sweep (see below)

Connectivity Sweep

switch_block_3d:
  connectivity: [1, 0.66, 0.33]

Custom Turn Patterns

When connection_type is "custom", you can define multiple turn patterns. Each input/output pair is a 4-element list representing turn offsets for [North, East, South, West]:

switch_block_3d:
  connection_type: ["custom"]
  custom_patterns:
    - input:  [0, 0, 0, 0]     # subset
      output: [0, 0, 0, 0]
    - input:  [0, 1, 2, 3]     # wilton variant 1
      output: [0, 1, 2, 3]
    - input:  [0, 0, 0, 0]     # wilton variant 2
      output: [0, 1, 2, 3]
    - input:  [0, 0, 0, 0]     # offset
      output: [1, 1, 1, 1]

Note

Each pattern pair is tested as a linked parameter — they are not crossed with each other.

SB Location Patterns

Controls where 3D switch boxes are placed on the FPGA grid.

Pattern	Description
`"repeated_interval"`	3D SBs placed at regular intervals across the grid
`"random"`	3D SBs placed randomly
`"custom"`	User-defined placement via a CSV file

# Built-in pattern:
switch_block_3d:
  location_pattern: ["repeated_interval"]

# Custom CSV placement:
switch_block_3d:
  location_pattern: ["custom"]
  grid_csv_path: ["{lazagna_root}/setup_files/csv_patterns/rows_10x10_pattern.csv"]

CSV Pattern Format

When using "custom", provide a CSV file where:

X marks a 3D switch box location
O marks a regular 2D switch box location

Example CSV patterns are available in setup_files/csv_patterns/.

`interlayer_delay`

Controls the delay characteristics of vertical (inter-layer) connections.

Parameter	Type	Default	Description
`vertical_connectivity`	int	`1`	Number of vertical connections per switch block
`delay_ratio`	float or list	`[0.739]`	Ratio of vertical-to-horizontal delay. List = sweep.
`base_delay_switch`	string	`"L4_driver"`	Reference switch whose delay is used for scaling
`update_arch_delay`	bool	`true`	Whether to update the arch XML with scaled delays
`switch_pairs`	dict	(see below)	Mapping from base switch name → inter-layer switch name

interlayer_delay:
  delay_ratio: [0.5, 1.0, 2.0, 3.0, 5.0]

Default switch_pairs:

switch_pairs:
  L4_driver: "L4_inter_layer_driver"
  L16_driver: "L16_inter_layer_driver"
  ipin_cblock: "ipin_inter_layer_cblock"

Tip

Sweep across delay ratios to explore the impact of vertical interconnect delay: delay_ratio: [0.5, 1.0, 2.0, 3.0, 4.0, 5.0]

`advanced`

Catch-all for expert options.

Parameter	Type	Default	Description
`additional_vpr_options`	string	`""`	Extra CLI flags passed directly to VPR

advanced:
  additional_vpr_options: "--inner_num 0.5"

Parameter Sweeping

LaZagna automatically generates all combinations of parameters specified as lists. This is a powerful feature for design space exploration.

Independent Parameters

Parameters specified as lists are swept as a Cartesian product:

switch_block_3d:
  connectivity: [1, 0.66, 0.33]

placement:
  algorithm: ["cube_bb", "per_layer_bb"]

interlayer_delay:
  delay_ratio: [0.5, 1.0, 2.0]

This generates $3 \times 2 \times 3 = 18$ combinations.

Linked Parameters

Some parameters vary together. They are not crossed with each other — each entry is one run:

Architectures: each type + arch_file pair
Custom patterns: each input + output pair
Location + CSV: each location_pattern + grid_csv_path
Seeds: each seed value

Automatic Filtering

LaZagna automatically filters out invalid combinations:

"2d", "3d_cb", and "3d_cb_out_only" types are only valid with connection_type: "subset"
"2d" type only works with placement.algorithm: "cube_bb"
"2d", "3d_cb", and "3d_cb_out_only" types require connectivity: 1.0

Complete Example

Here is a full configuration file showing all sections with explicit values:

experiment_name: "full_example"

grid:
  width_3d: 10
  height_3d: 10
  width_2d: 15
  height_2d: 15
  channel_width: 50

architectures:
  - type: combined

benchmarks:
  directory: "{lazagna_root}/benchmarks/and2_or2"
  is_verilog: false

placement:
  algorithm: ["cube_bb"]

seeds:
  mode: fixed
  value: 1

switch_block_3d:
  connectivity: [1]
  connection_type: ["subset"]
  switch_name: "3D_SB_switch"
  segment_name: "3D_SB_connection"
  input_pattern: []
  output_pattern: []
  location_pattern: ["repeated_interval"]
  grid_csv_path: ""

interlayer_delay:
  vertical_connectivity: 1
  delay_ratio: [0.739]
  base_delay_switch: "L4_driver"
  update_arch_delay: true
  switch_pairs:
    L4_driver: "L4_inter_layer_driver"
    L16_driver: "L16_inter_layer_driver"
    ipin_cblock: "ipin_inter_layer_cblock"

advanced:
  additional_vpr_options: ""

Remember — you never need to write all of this. Thanks to the defaults system, the equivalent minimal version is:

experiment_name: "full_example"

YAML Configuration Guide

Key Concepts

Defaults

Sweeping Parameters

Linked Parameters

Path Placeholders

Quick Start

Minimal Setup File

Configuration Sections

Complete Reference

experiment_name

grid

architectures

Available Types

benchmarks

placement

seeds

switch_block_3d

Connectivity Sweep

Custom Turn Patterns

SB Location Patterns

CSV Pattern Format

interlayer_delay

advanced

Parameter Sweeping

Independent Parameters

Linked Parameters

Automatic Filtering

Complete Example

`experiment_name`

`grid`

`architectures`

`benchmarks`

`placement`

`seeds`

`switch_block_3d`

`interlayer_delay`

`advanced`