SystemVerilog Testbench Introduction

SystemVerilog Testbench Architecture

APB Interface

APB Transaction

APB Generator

APB Driver

APB Driver Phase 2

APB Monitor

APB Scoreboard

APB Environment

APB Testbench Top

RISC-V Processor (YARP) Interface

YARP Transaction

YARP Generator

YARP Driver

YARP Data Memory Model

YARP Monitor

YARP Scoreboard

YARP Testbench Top

DVCon 26 Hackathon Problem

Array Sum Limit

Array Index Sum Limit

Ball Draw No Repeat

Conditional Even Probability

Even Odd Index Value

Five Consecutive Ones

Frequency Constraint

Grouped Ones

Index Value Range

Leap Year

Matrix Rotation

Non Adjacent Ones

Power of 4

Dynamic Ranges

Recent Four Unique

Row Max Unique

Subarray Max Sum

Three Duplicates Only

Tic Tac Toe

Unique 3D Array

Weighted Popcount

Unique Sum

Split Array into Queues

# Split Array into Three Queues

## Problem Statement

Given a fixed array of integers, write constraints to split every element of the array into three separate queues — `queue0`, `queue1`, and `queue2` — such that each element from the original array ends up in exactly one queue, and the three queues are evenly balanced.

Your task is to write constraints on a randomized "bin selector" array that decides which queue each element of the given array is routed into:
1. Every element of the given array must be routed to exactly one of the three queues
2. Each queue must end up with the same number of elements
3. No element may be dropped, and no element may be duplicated across queues

## Constraints
- Given array size: 9 elements (fixed): `[12, 45, 7, 23, 89, 3, 56, 34, 19]`
- Number of queues: 3
- Each queue must receive exactly `ARRAY_SIZE / 3 = 3` elements
- `bin_id[i]` selects which queue `given_array[i]` is placed into: `bin_id[i]` ∈ {0, 1, 2}

## Examples

### Example 1:
```
Given array: [12, 45, 7, 23, 89, 3, 56, 34, 19]
bin_id:      [ 0,  1, 2,  0,  1, 2,  0,  1,  2]

queue0: [12, 23, 56]
queue1: [45, 89, 34]
queue2: [7, 3, 19]
```
Explanation: Each queue gets exactly 3 elements, and every element from the given array appears exactly once across the three queues.

### Example 2:
```
Given array: [12, 45, 7, 23, 89, 3, 56, 34, 19]
bin_id:      [ 0,  0, 0,  1,  1, 1,  2,  2,  2]

queue0: [12, 45, 7]
queue1: [23, 89, 3]
queue2: [56, 34, 19]
```
Explanation: A different valid split. The order of bin assignment doesn't matter — only that every queue ends up with 3 elements and every array element is accounted for exactly once.

### Example 3 (Invalid):
```
bin_id: [0, 0, 0, 0, 1, 1, 2, 2, 2]

queue0: [12, 45, 7, 23]  (4 elements)
queue1: [89, 3]          (2 elements)
queue2: [56, 34, 19]     (3 elements)
```
Explanation: `queue0` has 4 elements while `queue1` has only 2 — the split is not balanced.

### Example 4 (Invalid):
```
bin_id: [0, 1, 2, 0, 1, 2, 0, 1, 1]

queue0: [12, 23, 56]
queue1: [45, 89, 34, 19]
queue2: [7, 3]
```
Explanation: `queue1` has 4 elements while `queue2` has only 2 — the split is not balanced, even though every element still appears exactly once.


# Split Array into Three Queues

## Problem Statement

Given a fixed array of integers, write constraints to split every element of the array into three separate queues — `queue0`, `queue1`, and `queue2` — such that each element from the original array ends up in exactly one queue, and the three queues are evenly balanced.

Your task is to write constraints on a randomized "bin selector" array that decides which queue each element of the given array is routed into:
1. Every element of the given array must be routed to exactly one of the three queues
2. Each queue must end up with the same number of elements
3. No element may be dropped, and no element may be duplicated across queues

## Constraints
- Given array size: 9 elements (fixed): `[12, 45, 7, 23, 89, 3, 56, 34, 19]`
- Number of queues: 3
- Each queue must receive exactly `ARRAY_SIZE / 3 = 3` elements
- `bin_id[i]` selects which queue `given_array[i]` is placed into: `bin_id[i]` ∈ {0, 1, 2}

## Examples

### Example 1:
```
Given array: [12, 45, 7, 23, 89, 3, 56, 34, 19]
bin_id:      [ 0,  1, 2,  0,  1, 2,  0,  1,  2]

queue0: [12, 23, 56]
queue1: [45, 89, 34]
queue2: [7, 3, 19]
```
Explanation: Each queue gets exactly 3 elements, and every element from the given array appears exactly once across the three queues.

### Example 2:
```
Given array: [12, 45, 7, 23, 89, 3, 56, 34, 19]
bin_id:      [ 0,  0, 0,  1,  1, 1,  2,  2,  2]

queue0: [12, 45, 7]
queue1: [23, 89, 3]
queue2: [56, 34, 19]
```
Explanation: A different valid split. The order of bin assignment doesn't matter — only that every queue ends up with 3 elements and every array element is accounted for exactly once.

### Example 3 (Invalid):
```
bin_id: [0, 0, 0, 0, 1, 1, 2, 2, 2]

queue0: [12, 45, 7, 23]  (4 elements)
queue1: [89, 3]          (2 elements)
queue2: [56, 34, 19]     (3 elements)
```
Explanation: `queue0` has 4 elements while `queue1` has only 2 — the split is not balanced.

### Example 4 (Invalid):
```
bin_id: [0, 1, 2, 0, 1, 2, 0, 1, 1]

queue0: [12, 23, 56]
queue1: [45, 89, 34, 19]
queue2: [7, 3]
```
Explanation: `queue1` has 4 elements while `queue2` has only 2 — the split is not balanced, even though every element still appears exactly once.

## Starter Code Pointer

The constraint logic is implemented in the `split_array_three_queues.sv` file under the `verilog/` directory. This constraint class defines:
1. A fixed input array of 9 integers (`given_array`)
2. A randomized `bin_id` array that decides, for every index, which of the three queues that element goes into
3. Three queues (`queue0`, `queue1`, `queue2`) that get populated based on `bin_id`

Your implementation should ensure `bin_id` only takes values in {0, 1, 2}, and that each of the three resulting queues ends up with exactly `ARRAY_SIZE / 3` elements while covering every element of `given_array` exactly once.


## Key Concepts

1. **Indirection through a bin selector**: Instead of randomizing the queues directly (which makes "every element appears exactly once" hard to express), a single `rand` array (`bin_id`) decides the destination queue for each fixed index. The queues themselves are built deterministically in `post_randomize()`, which structurally guarantees no element is ever dropped or duplicated.
2. **Counting with `sum() with`**: `bin_id.sum() with (int'(item == value))` counts how many entries of `bin_id` equal `value`. This is the standard idiom for expressing per-category cardinality constraints without an explicit loop and counter variable.
3. **Balanced partitioning**: Constraining the count of each bin value to `ARRAY_SIZE/NUM_QUEUES` forces an even three-way split; the solver is free to choose *which* elements land in which queue, so many valid solutions exist.

## Solver Strategy

The constraint solver uses:
- A range constraint on `bin_id[i]` to restrict each entry to one of the three valid queue IDs
- Three cardinality constraints (via `sum() with`) to force an even split across queues
- `post_randomize()` to materialize the queues from the solved `bin_id` array, so the partition constraint (each element in exactly one queue) never has to be expressed directly

# Split Array into Three Queues - Solution

```verilog
// --------------------------------------------------------
// Copyright (C) quicksilicon.io - All Rights Reserved
//
// Unauthorized copying of this file, via any medium is
// strictly prohibited
// Proprietary and confidential
// --------------------------------------------------------

// --------------------------------------------------------
// Split Array Three Queues - Constraint
// --------------------------------------------------------

package split_array_three_queues_pkg;
  class split_array_three_queues;
    // --------------------------------------------------------
    // Properties
    // --------------------------------------------------------
    localparam int ARRAY_SIZE = 9;
    localparam int NUM_QUEUES = 3;

    // Given array whose elements must be split across the three queues
    int given_array[ARRAY_SIZE] = '{12, 45, 7, 23, 89, 3, 56, 34, 19};

    // bin_id[i] selects which queue given_array[i] is routed to
    rand int bin_id[ARRAY_SIZE];

    // Resulting queues, populated in post_randomize()
    int queue0[$];
    int queue1[$];
    int queue2[$];

    // --------------------------------------------------------
    // Constraints
    // --------------------------------------------------------
    constraint bin_range_c {
      // Every element must be routed to queue0, queue1 or queue2
      foreach (bin_id[i]) {
        bin_id[i] inside {[0:NUM_QUEUES-1]};
      }
    }

    constraint balanced_split_c {
      // Every queue must receive exactly ARRAY_SIZE/NUM_QUEUES elements
      bin_id.sum() with (int'(item == 0)) == ARRAY_SIZE/NUM_QUEUES;
      bin_id.sum() with (int'(item == 1)) == ARRAY_SIZE/NUM_QUEUES;
      bin_id.sum() with (int'(item == 2)) == ARRAY_SIZE/NUM_QUEUES;
    }

    // --------------------------------------------------------
    // Post-randomize to build the three queues from bin_id
    // --------------------------------------------------------
    function void post_randomize();
      queue0.delete();
      queue1.delete();
      queue2.delete();
      foreach (given_array[i]) begin
        case (bin_id[i])
          0: queue0.push_back(given_array[i]);
          1: queue1.push_back(given_array[i]);
          2: queue2.push_back(given_array[i]);
        endcase
      end
    endfunction

  endclass
endpackage
```
