Codegen to Testbench C++

Given the PDA-QP parameters `PDAQPAlgoConfig`, generate the reference
implementation in C++20: `constants.hpp` and `problem-def.hpp`.

Also, given the hardware accelerator config `PDAQPHWConfig`, generate
the corresponding config file in Chisel HDL language `Constants.scala`.

The hardware accelerator project code will be released soon.

Author: antonysigma

cvxpygen/hwgen/codegen.py

@@ -0,0 +1,69 @@
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+from numpy import concatenate, hstack, newaxis
+
+from cvxpygen.hwgen.firmware_models import (
+    ExecutionEnvironment,
+)
+from cvxpygen.hwgen.hw_models import PDAQPHWConfig
+from cvxpygen.hwgen.models import PDAQPAlgoConfig
+
+env = Environment(
+    loader=PackageLoader("cvxpygen.hwgen"), autoescape=select_autoescape()
+)
+
+
+def generateHWAccCode(config: PDAQPHWConfig, target_dir: Path) -> Path:
+    """Given the high-level hardware accelerator design for
+    PDA-QP solver, generate the design in the Chisel language."""
+
+    template = env.get_template("hwacc/Constants.scala.j2")
+    rendered = template.render(config=config)
+
+    outfile_path = target_dir / "Constants.scala"
+    with open(outfile_path, "w") as f:
+        f.write(rendered)
+
+    return outfile_path
+
+
+def generateTestbenchCode(
+    config: PDAQPAlgoConfig,
+    fixed_point_precision: int,
+    execution_environment: ExecutionEnvironment,
+    target_dir: Path,
+) -> tuple[Path, Path]:
+    """Given the high-level algorithm design for
+    PDA-QP solver, generate the design in the Chisel language."""
+
+    constants_hpp_path = target_dir / "constants.hpp"
+    with open(constants_hpp_path, "w") as f:
+        rendered = env.get_template("testbench/constants.hpp.j2").render(
+            problem_size=config.problem_size,
+            Q=fixed_point_precision,
+        )
+        f.write(rendered)
+
+    problem_def_hpp_path = target_dir / "problem-def.hpp"
+    with open(problem_def_hpp_path, "w") as f:
+        # TODO (antonysigma): The shape of the halfplanes normal and
+        # offset are erased. Modify the C++ project to preserve the shape.
+
+        assert config.feedbacks.scale.shape[0] == config.feedbacks.offset.shape[0]
+        assert config.feedbacks.scale.shape[1] == config.feedbacks.offset.shape[1]
+        assert config.feedbacks.scale.shape[2] == config.problem_size.n_parameter
+
+        rendered = env.get_template("testbench/problem-def.hpp.j2").render(
+            half_planes=hstack(
+                (config.half_planes.scale, config.half_planes.offset[:, newaxis])
+            ),
+            feedbacks=concatenate(
+                (config.feedbacks.scale, config.feedbacks.offset[..., newaxis]),
+                axis=-1,
+            ),
+            tree_nodes=config.tree_nodes,
+        )
+        f.write(rendered)
+
+    return constants_hpp_path, problem_def_hpp_path

cvxpygen/hwgen/decode.py

@@ -5,7 +5,7 @@
 from cvxpygen.hwgen.c_parsing.array_visitor import FloatArrayVisitor, IntArrayVisitor
 from cvxpygen.hwgen.c_parsing.grammars import pdaqp_c_grammar, pdaqp_header_grammar
 from cvxpygen.hwgen.c_parsing.header_visitor import HeaderVisitor
-from cvxpygen.hwgen.models import MultiplyAddFP32, PDAQPAlgoConfig
+from cvxpygen.hwgen.models import BinaryTree, MultiplyAddFP32, PDAQPAlgoConfig
 
 
 def decode(c_path: Path, h_path: Path) -> PDAQPAlgoConfig:
@@ -41,19 +41,32 @@ def decode(c_path: Path, h_path: Path) -> PDAQPAlgoConfig:
         == 0
     )
     feedbacks = float_arrays.arrays["pdaqp_feedbacks"].data.reshape(
-        -1, n_parameter + 1, n_solution
+        -1, n_solution, n_parameter + 1
     )
 
     assert "pdaqp_hp_list" in int_arrays.arrays
     assert int_arrays.arrays["pdaqp_hp_list"].data.max() <= 65535
 
+    assert "pdaqp_jump_list" in int_arrays.arrays
+    assert int_arrays.arrays["pdaqp_jump_list"].data.max() <= 65535
+
+    assert (
+        int_arrays.arrays["pdaqp_hp_list"].data.size
+        == int_arrays.arrays["pdaqp_jump_list"].data.size
+    )
+
     return PDAQPAlgoConfig(
         header_visitor.problem_size,
-        tree_nodes=int_arrays.arrays["pdaqp_hp_list"].data.astype(uint16),
+        tree_nodes=BinaryTree(
+            halfplane_or_feedback_id=int_arrays.arrays["pdaqp_hp_list"].data.astype(
+                uint16
+            ),
+            jump=int_arrays.arrays["pdaqp_jump_list"].data.astype(uint16),
+        ),
         half_planes=MultiplyAddFP32(
             halfplanes[:, :n_parameter], halfplanes[:, n_parameter]
         ),
         feedbacks=MultiplyAddFP32(
-            feedbacks[:, :n_parameter], feedbacks[:, n_parameter]
+            feedbacks[..., :n_parameter], feedbacks[..., n_parameter]
         ),
     )

cvxpygen/hwgen/firmware_models.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass
+from enum import Enum
+
+
+class OperatingSystem(Enum):
+    Linux = 0
+    NoOS = 1
+
+
+class HardwareCapability(Enum):
+    BranchPrediction = 0
+    SIMDInstructions = 1
+    InstructionCache = 2
+
+
+@dataclass
+class ExecutionEnvironment:
+    os: OperatingSystem
+    cpu_bits: int
+    hardware_capabilities: list[HardwareCapability]
+
+
+LINUX_AMD64 = ExecutionEnvironment(
+    os=OperatingSystem.Linux,
+    cpu_bits=64,
+    hardware_capabilities=[
+        HardwareCapability.SIMDInstructions,
+        HardwareCapability.BranchPrediction,
+        HardwareCapability.InstructionCache,
+    ],
+)
+
+ARM64 = ExecutionEnvironment(
+    os=OperatingSystem.NoOS,
+    cpu_bits=32,
+    hardware_capabilities=[
+        HardwareCapability.SIMDInstructions,
+        HardwareCapability.BranchPrediction,
+    ],
+)
+
+ATMETA8 = ExecutionEnvironment(
+    os=OperatingSystem.NoOS,
+    cpu_bits=8,
+    hardware_capabilities=[],
+)

cvxpygen/hwgen/hw_models.py

@@ -1,16 +1,18 @@
 from dataclasses import dataclass
 
-from numpy import uint16
-from numpy.typing import NDArray
-
-from cvxpygen.hwgen.models import MultiplyAddFix16, MultiplyAddFP32, ProblemSize
+from cvxpygen.hwgen.models import (
+    BinaryTree,
+    MultiplyAddFix16,
+    MultiplyAddFP32,
+    ProblemSize,
+)
 
 
 @dataclass
 class TreeWalkerFSM:
     """A tree walking module implemented as finite state machine."""
 
-    tree_nodes: NDArray[uint16]
+    tree_nodes: BinaryTree
 
 
 @dataclass

cvxpygen/hwgen/models.py

@@ -41,10 +41,20 @@ class MultiplyAddFix16:
     Q: int = 14
 
 
+@dataclass
+class BinaryTree:
+    halfplane_or_feedback_id: NDArray[uint16]
+    jump: NDArray[uint16]
+
+    @property
+    def size(self) -> int:
+        return self.jump.size
+
+
 @dataclass
 class PDAQPAlgoConfig:
     problem_size: ProblemSize
-    tree_nodes: NDArray[uint16]
+    tree_nodes: BinaryTree
     half_planes: MultiplyAddFP32
     feedbacks: MultiplyAddFP32
 

cvxpygen/hwgen/templates/hwacc/Constants.scala.j2

@@ -0,0 +1,51 @@
+import scala.util.Random
+import chisel3._
+import chisel3.util._
+
+object Constants {
+    val rnd = new Random()
+
+    // BEGIN compile-time constants (already quantized)
+    final val n_solutions = {{ config.problem_size.n_solution }}
+    final val n_params    = {{ config.problem_size.n_parameter }} 
+    final val n_nodes     = {{ config.n_tree_nodes }}
+    final val n_feedbacks = {{ config.n_feedbacks }}
+    final val Q           = {{ config.feedback_module.param.Q }}
+
+    final val hyperplane_normal = Seq(
+        {% for item in config.half_planes_module.param.scale.ravel() -%}
+                {{ item }},
+        {% endfor -%}
+    )
+
+    final val hyperplane_offset = Seq(
+        {% for item in config.half_planes_module.param.offset.ravel() -%}
+                {{ item }},
+        {% endfor -%}
+    )
+
+    final val feedbackA = Seq(
+        {% for item in config.feedback_module.param.scale.ravel() -%}
+                {{ item }},
+        {% endfor -%}
+    )
+
+    final val feedbackC = Seq(
+        {% for item in config.feedback_module.param.offset.ravel() -%}
+                {{ item }},
+        {% endfor -%}
+    )
+
+    final val hpList   = Seq(
+        {% for item in config.tree_walker.tree_nodes.halfplane_or_feedback_id -%}
+                {{ item }},
+        {% endfor -%}
+    )
+
+    final val jumpList = Seq(
+        {% for item in config.tree_walker.tree_nodes.jump -%}
+                {{ item }},
+        {% endfor -%}
+    )
+    // END compile-time constants (already quantized)
+}

cvxpygen/hwgen/templates/testbench/constants.hpp.j2

@@ -0,0 +1,13 @@
+#pragma once
+#include <cstdint>
+
+#include "fixed_math.hpp"
+#include "log2ceil.hpp"
+
+constexpr uint16_t n_parameter = {{ problem_size.n_parameter }};
+constexpr uint16_t n_solution = {{ problem_size.n_solution }};
+
+using DataFormat = math::fixed<int16_t, {{ Q }}>;
+using AccuDataFormat = math::fixed<int32_t, {{ Q }} * 2 - log2ceil(n_parameter) - 1>;
+
+static_assert(DataFormat::_Q <= AccuDataFormat::_Q, "Insufficient precision for the numerical product");

cvxpygen/hwgen/templates/testbench/problem-def.hpp.j2

@@ -0,0 +1,25 @@
+#pragma once
+#include <array>
+#include <cstdint>
+
+constexpr std::array<float, {{ half_planes.size }}> pdaqp_halfplanes{
+    {% for item in half_planes.ravel() -%}
+        {{ item }}f,
+    {% endfor -%}
+};
+constexpr std::array<float, {{ feedbacks.size }}> pdaqp_feedbacks = {
+    {% for item in feedbacks.ravel() -%}
+        {{ item }}f,
+    {% endfor -%}
+};
+
+constexpr std::array<uint16_t, {{ tree_nodes.halfplane_or_feedback_id.size }}> pdaqp_hp_list{
+    {% for item in tree_nodes.halfplane_or_feedback_id.ravel() -%}
+        {{ item }},
+    {% endfor -%}
+};
+constexpr std::array<uint16_t, {{ tree_nodes.jump.size }}> pdaqp_jump_list{
+    {% for item in tree_nodes.jump.ravel() -%}
+        {{ item }},
+    {% endfor -%}
+};

tests/hwgen/test_firmware_codegen.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+from numpy import float32, uint16
+from numpy.random import randint, randn
+from numpy.typing import NDArray
+
+from cvxpygen.hwgen.codegen import generateTestbenchCode
+from cvxpygen.hwgen.firmware_models import LINUX_AMD64
+from cvxpygen.hwgen.models import (
+    BinaryTree,
+    MultiplyAddFP32,
+    PDAQPAlgoConfig,
+    ProblemSize,
+)
+
+
+def test_codegen() -> None:
+    problem_size = ProblemSize(2, 3)
+    n_tree_nodes = 5
+    n_feedbacks = 3
+
+    def generate_rand(size: tuple) -> NDArray[float32]:
+        vmax = 20_000
+        return randn(*size).astype(float32)
+
+    config = PDAQPAlgoConfig(
+        problem_size,
+        tree_nodes=BinaryTree(
+            halfplane_or_feedback_id=randint(0, n_tree_nodes, size=n_tree_nodes).astype(
+                uint16
+            ),
+            jump=randint(0, n_tree_nodes, size=n_tree_nodes).astype(uint16),
+        ),
+        half_planes=MultiplyAddFP32(
+            generate_rand(
+                (n_tree_nodes - n_feedbacks, problem_size.n_parameter),
+            ),
+            generate_rand((n_tree_nodes - n_feedbacks,)),
+        ),
+        feedbacks=MultiplyAddFP32(
+            generate_rand(
+                (n_feedbacks, problem_size.n_solution, problem_size.n_parameter),
+            ),
+            generate_rand(
+                (
+                    n_feedbacks,
+                    problem_size.n_solution,
+                ),
+            ),
+        ),
+    )
+
+    fixed_point_precision = 14
+    constants_hpp, problem_def_hpp = generateTestbenchCode(
+        config, fixed_point_precision, LINUX_AMD64, Path("/tmp")
+    )
+    assert constants_hpp.exists()
+    assert problem_def_hpp.exists()