holoso 0.1.0__tar.gz

holoso-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: holoso
+Version: 0.1.0
+Summary: A simple Python-to-Verilog synthesizer for numeric kernels, control systems, and DSP.
+Requires-Python: >=3.14
+Requires-Dist: numpy~=2.4
+Requires-Dist: scipy~=1.17
+Requires-Dist: sympy~=1.14
+Provides-Extra: test
+Requires-Dist: cocotb~=2.0; extra == "test"
+Requires-Dist: jaxtyping~=0.3; extra == "test"
+Requires-Dist: pytest~=9.0; extra == "test"
+Provides-Extra: format
+Requires-Dist: black~=26.5; extra == "format"
+Provides-Extra: typecheck
+Requires-Dist: mypy~=2.1; extra == "typecheck"

holoso-0.1.0/README.md

@@ -0,0 +1,107 @@
+<div align="center">
+
+<img src="docs/holoso-logo-128.png" width="60px">
+
+<h1>Holoso</h1>
+
+_Simple high-level synthesis of portable Verilog from idiomatic Python_
+
+[![Try online](https://img.shields.io/badge/try_online-holoso.digital-black?color=ff0000)](https://holoso.digital/)
+[![Forum](https://img.shields.io/discourse/https/forum.zubax.com/users.svg?logo=discourse&color=ff0000)](https://forum.zubax.com)
+
+</div>
+
+-----
+
+Holoso converts a subset of idiomatic Python into synthesizable and verifiable Verilog.
+It is primarily designed for heavy numerical code which is abundant in control systems and DSP
+where manual RTL coding is inefficient and error-prone.
+
+Holoso focuses on Python because this is a popular language in modeling, system design, and verification domains;
+ability to generate production HDL directly from the original model allows the designer to work with much simpler
+harnesses and iterate faster.
+
+See [PRIOR_ART.md](PRIOR_ART.md) for a detailed review of existing alternatives,
+and why none are good enough for practical use.
+
+Holoso is under active development and as such it has no burden of backward compatibility.
+Breaking changes will occur regularly without notice until v1.0 is out.
+Many critical features are missing which may limit applicability beyond applications that we are immediately involved with.
+Contributions of any kind are emphatically welcome!
+
+<img src="docs/hero.png" width="900px">
+
+## Design
+
+Holoso implements essentially a separate programming language whose syntax is a strict subset of Python,
+and whose semantics is largely equivalent to Python with minor deviations that make sense in chip design context.
+Save for the minor differences in semantics, Holoso ensures that one can execute the original Python code
+and run the generated circuit (RTL) side by side, and obtain equivalent results (bit-exact unless floating points
+are used, in which case small errors may creep up, due to the inherent limitations of floating points).
+
+Unlike most (all known to us) HLS engines out there, Holoso does not generate a straight-line II=1 pipeline
+because this is rarely what you actually need in practice; instead, it designs a narrowly specialized
+computing core (a zero-instruction-set processor) with custom microcode, and statically schedules a program for the
+designed core. Being in control of both the core synthesis and the program compilation, Holoso tends to generate
+extremely efficient designs in terms of cycle latency and chip area utilization compared to the state of the art.
+
+Holoso outputs a purely portable and vendor-agnostic Verilog that can be fed into thid-party synthesis tools as-is,
+along with its support library implementing various arithmetic operators. So far it has been tested at least with
+Yosys (ECP5), Diamond (ECP5), and Vivado (Artix-7).
+
+By default, Holoso is tuned for the minimum cycle latency and minimum $f_\max$.
+If timing closure fails, one needs to locate the critical path and enable the staging knob that inserts a
+register stage into the offending path; then re-synthesize and repeat until timings close.
+
+Holoso has its own efficient floating point engine that is a subset of IEEE-754, omitting support for subnormals and NaN.
+Arbitrary exponent and significand bit widths are supported (the IEEE-754 defaults map poorly onto FPGA DSP tiles).
+
+Along with the synthesized Verilog, Holoso produces a Cocotb co-simulation testbench and a detailed and beautiful HTML
+report that provides a human-friendly view of the processor and the microcode sequence constructed by the synthesizer.
+
+>*You can SEE the pipeline — every cycle, every landing, every spill. It's gorgeous. People love it.*
+>*They come up to me with tears in their eyes, they say sir, that schedule report, it's the most beautiful report we have ever seen.*
+
+For a detailed review of the design and trade-offs, please refer to `DESIGN.md`.
+
+## Usage
+
+Unlike most tools in this domain, Holoso is trivial to set up and get started with; it is not a framework.
+
+Install: `pip install holoso`.
+
+```python
+# Select the floating-point format you wish to use.
+# Ideally, wman (mantissa width) should be a multiple of DSP tile operand width.
+float_format = holoso.FloatFormat(wexp=6, wman=18)
+
+# Define the numerical operators. This is where you can configure additional stages to close timings.
+ops = holoso.OpConfig(
+    holoso.FAddOperator(float_format),
+    holoso.FMulOperator(float_format),
+    holoso.FDivOperator(float_format),
+    holoso.FMulILog2OperatorFamily(float_format),
+    holoso.FCmpOperator(float_format),
+)
+
+# Run Holoso -- construct the processor and the microcode.
+# The results are returned in-memory; you can write them to disk where you want.
+# They include the generated Verilog module, the fixed holoso_support.v/.vh, testbench, and the reports.
+result = holoso.synthesize(your_function_or_method_here)
+
+# Write the files -- this is usually what you want.
+out = result.write(Path(__file__).resolve().parent)
+
+# Show what's been written.
+for filename, path in out.items():
+    print(f"{filename}: {path}")
+```
+
+See the `examples/` directory for self-contained usage examples.
+
+## Verification
+
+Just say `nox`. Read the `noxfile.py` and `DESIGN.md` for details.
+
+You may find the [zubax-fpga-toolchain](https://github.com/Zubax/fpga-toolchain-docker/pkgs/container/zubax-fpga-toolchain)
+container useful as it comes with all of the required tools out of the box.

holoso-0.1.0/holoso/__init__.py

@@ -0,0 +1,48 @@
+"""Holoso: a narrow Python-to-Verilog synthesizer for numeric kernels."""
+
+from ._api import synthesize as synthesize, SynthesisResult as SynthesisResult
+from ._lir import (
+    ControlInputPort as ControlInputPort,
+    ControlOutputPort as ControlOutputPort,
+    ControlPort as ControlPort,
+    DataInputPort as DataInputPort,
+    DataOutputPort as DataOutputPort,
+    DataPort as DataPort,
+    Direction as Direction,
+    Port as Port,
+)
+from ._type import (
+    BoolType as BoolType,
+    FloatFormat as FloatFormat,
+    FloatType as FloatType,
+    LogicalPort as LogicalPort,
+    ScalarType as ScalarType,
+)
+from ._value import FloatValue as FloatValue
+from ._errors import (
+    HolosoError as HolosoError,
+    MissingIntrinsic as MissingIntrinsic,
+    SourceUnavailable as SourceUnavailable,
+    SynthesisError as SynthesisError,
+    UnsupportedConstruct as UnsupportedConstruct,
+)
+
+from ._backend.cocotb import CocotbOutput as CocotbOutput
+from ._backend.html import HtmlOutput as HtmlOutput
+from ._backend.numerical import (
+    NumericalModel as NumericalModel,
+    NumericalSimulator as NumericalSimulator,
+)
+from ._backend.verilog import VerilogOutput as VerilogOutput
+
+from ._operators import (
+    FAddOperator as FAddOperator,
+    FDivOperator as FDivOperator,
+    FMulILog2OperatorFamily as FMulILog2OperatorFamily,
+    FMulOperator as FMulOperator,
+    FCmpOperator as FCmpOperator,
+    OpConfig as OpConfig,
+)
+
+__version__ = "0.1.0"
+__url__ = "https://github.com/Zubax/holoso"

holoso-0.1.0/holoso/_api.py

@@ -0,0 +1,163 @@
+"""The public synthesis entry point."""
+
+from collections.abc import Callable
+from typing import Any
+from dataclasses import dataclass, fields
+from pathlib import Path
+import inspect
+import logging
+import re
+
+from ._backend.cocotb import generate as generate_testbench, CocotbOutput
+from ._backend.html import generate as generate_html, HtmlOutput
+from ._backend.numerical import generate as generate_model, NumericalModel
+from ._backend.verilog import generate as generate_verilog, VerilogOutput
+
+from ._frontend import lower as lower_frontend
+from ._hir import optimize
+from ._lir import ControlPort, DataInputPort, DataOutputPort, Port, build
+from ._mir import lower as lower_to_mir
+from ._operators import OpConfig
+
+type Target = Callable[..., Any]
+"""
+Currently supported targets are:
+- A plain stateless function or lambda.
+- A bound method of a class instance -- stateful. Public attributes become additional output ports.
+- Later on we may potentially add support for multiple methods per class, where the generated module will provide
+  a selector port to choose which method to execute, all sharing the same state. In this case we would accept
+  a tuple containing the class type and a list of its unbound methods. This remains to be seen.
+"""
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class SynthesisResult:
+    """Everything produced by a synthesis run, held in memory. Nothing is written to disk unless requested."""
+
+    module_name: str
+
+    ports: list[Port]
+    input_ports: list[DataInputPort]
+    output_ports: list[DataOutputPort]
+    control_ports: list[ControlPort]
+
+    initiation_interval: tuple[int, int | None]  # (min II, max II or None if data-dependent)
+    verilog_output: VerilogOutput
+    numerical_model: NumericalModel
+    cocotb_output: CocotbOutput
+    html_output: HtmlOutput
+
+    def write(self, out_dir: Path | str) -> dict[str, Path]:
+        """
+        Write every artifact to ``out_dir`` and return the written paths keyed by filename.
+        This is the only Holoso operation that touches the filesystem.
+        """
+        directory = Path(out_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+        files: dict[str, str] = {
+            f"{self.module_name}.v": self.verilog_output.verilog,
+            **self.verilog_output.support_files,
+            f"test_{self.module_name}.py": self.cocotb_output.testbench,
+            f"{self.module_name}.html": self.html_output.html,
+        }
+        written: dict[str, Path] = {}
+        for filename, content in files.items():
+            path = directory / filename
+            path.write_text(content, encoding="utf-8")
+            written[filename] = path
+        return written
+
+
+def synthesize(target: Target, /, ops: OpConfig, *, name: str | None = None) -> SynthesisResult:
+    """
+    Synthesize ``target`` (a plain function or a bound method of a constructed instance) into RTL.
+    ``ops`` is the operator configuration, constructed explicitly by the caller: each field fixes one operator's
+    float format and parameters, including any pipeline-stage knobs that lengthen its latency to ease timing closure.
+    ``name`` overrides the generated module name (inferred from target by default).
+    """
+    logging.basicConfig(level=logging.INFO, format="%(levelname)-5.5s %(name)s: %(message)s")  # no-op if already setup
+    module_name: str = name or _default_module_name(target)
+    _validate_module_name(module_name)
+    _logger.info("Synthesis start: module=%r target=%r", module_name, target)
+    _logger.info("Configured operators:")
+    for field in fields(ops):
+        _logger.info("\t%s: %s", field.name, getattr(ops, field.name))
+
+    hir = optimize(lower_frontend(target))
+    _logger.info("HIR:\n\tinputs=%s\n\toutputs=%s\n\thir_nodes=%d", hir.input_ids, hir.outputs, len(hir.nodes))
+
+    mir = lower_to_mir(hir, ops)
+
+    lir = build(mir, module_name)
+    _logger.info("LIR ports:\n\t%s", "\n\t".join(f"{port}" for port in lir.ports))
+
+    verilog_output = generate_verilog(lir)
+    html_output = generate_html(lir, verilog_output)
+    model = generate_model(lir)
+    cocotb_output = generate_testbench(model)
+
+    latency_is_exact = len(lir.blocks) == 1  # a straight-line kernel has one fixed path; branches/loops vary by data
+    ii = (lir.min_initiation_interval, lir.min_initiation_interval if latency_is_exact else None)
+    _logger.info("Generated Verilog: %s; II [min,max]: %s cycles", verilog_output, ii)
+    return SynthesisResult(
+        module_name=module_name,
+        ports=lir.ports,
+        input_ports=lir.input_ports,
+        output_ports=lir.output_ports,
+        control_ports=lir.control_ports,
+        initiation_interval=ii,
+        verilog_output=verilog_output,
+        numerical_model=model,
+        cocotb_output=cocotb_output,
+        html_output=html_output,
+    )
+
+
+def _default_module_name(target: Target) -> str:
+    if inspect.ismethod(target):
+        n = type(target.__self__).__name__
+        if "__" not in target.__name__:
+            n += f"_{target.__name__}"
+        return n
+    return str(getattr(target, "__name__", "kernel"))
+
+
+def _validate_module_name(name: str) -> None:
+    if _MODULE_NAME.fullmatch(name) is None:
+        raise ValueError(f"module name {name!r} is not a valid identifier; expected [A-Za-z_][A-Za-z0-9_]*")
+    if name in _BLACKLIST:
+        raise ValueError(f"module name {name!r} is a reserved keyword; choose another name")
+    if name.lower().startswith("holoso"):
+        raise ValueError(f"module name {name!r} uses the reserved 'holoso' prefix; choose another name")
+
+
+_MODULE_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+# Keywords from supported HDLs etc. that are not valid module names. Includes Verilog and VHDL keywords.
+_BLACKLIST = frozenset("""
+always and assign automatic begin buf bufif0 bufif1 case casex casez cell cmos config deassign default defparam
+design disable edge else end endcase endconfig endfunction endgenerate endmodule endprimitive endspecify endtable
+endtask event for force forever fork function generate genvar highz0 highz1 if ifnone incdir include initial inout
+input instance integer join large liblist library localparam macromodule medium module nand negedge nmos nor
+noshowcancelled not notif0 notif1 or output parameter pmos posedge primitive pull0 pull1 pulldown pullup
+pulsestyle_onevent pulsestyle_ondetect rcmos real realtime reg release repeat rnmos rpmos rtran rtranif0 rtranif1
+scalared showcancelled signed small specify specparam strong0 strong1 supply0 supply1 table task time tran tranif0
+tranif1 tri tri0 tri1 triand trior trireg unsigned use uwire vectored wait wand weak0 weak1 while wire wor xnor xor
+abs access after alias all architecture array assert attribute block body buffer bus component configuration constant
+context disconnect downto elsif entity exit file generic group guarded impure in inertial is label linkage literal
+loop map mod new next null of on open others out package port postponed procedure process protected pure
+range record register reject rem report return rol ror select severity signal shared sla sll sra srl subtype
+then to transport type unaffected units until variable when with
+accept_on always_comb always_ff always_latch assume before bind bins binsof bit break byte chandle checker
+class clocking const constraint continue cover covergroup coverpoint cross dist do endchecker endclass
+endclocking endgroup endinterface endpackage endprogram endproperty endsequence enum expect export extends extern
+final first_match foreach forkjoin global iff ignore_bins illegal_bins implements implies import inside int interface
+intersect join_any join_none let logic longint matches modport nettype packed priority program property rand randc
+randcase randsequence ref reject_on restrict s_always s_eventually s_nexttime s_until s_until_with sequence shortint
+shortreal soft solve static string strong struct super sync_accept_on sync_reject_on tagged this throughout
+timeprecision timeunit typedef union unique unique0 var virtual void wait_order weak wildcard within
+assume_guarantee eventually fairness interconnect local nexttime restrict_guarantee untyped until_with vmode vprop vunit
+false none true as async await def del elif except finally from lambda nonlocal pass raise try yield
+""".split())

holoso-0.1.0/holoso/_backend/__init__.py

@@ -0,0 +1,4 @@
+"""
+Output backends: each ``holoso/_backend/<name>`` exposes a stateless ``generate(...) -> <Name>Output``.
+Backends are imported as needed.
+"""

holoso-0.1.0/holoso/_backend/cocotb.py

@@ -0,0 +1,195 @@
+"""
+The cocotb backend: a self-contained, self-checking testbench for a generated module.
+
+``generate`` embeds the module's :class:`NumericalModel` handle into a standalone cocotb test. The bench unpickles the
+handle, elaborates a :class:`NumericalSimulator`, and ticks it in cycle-by-cycle lockstep with the DUT: each clock it
+asserts that ``out_valid``/``in_ready`` agree (so the model reaches ``out_valid`` on exactly the DUT's cycle -- the
+data-dependent latency check) and that the output bits match when valid, back-pressure included. The model is bit-exact
+to the RTL, so the output check needs no tolerance.
+
+The input sequence is either an explicit list of vectors supplied by the caller (replayed verbatim) or, when none is
+given, a default random sweep drawn from a fixed seed. The seed also drives the back-pressure stalls, so every generated
+bench is fully reproducible.
+"""
+
+import base64
+import pickle
+import zlib
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .numerical import NumericalModel
+
+# language=python
+_TEMPLATE = '''\
+"""
+Auto-generated by Holoso: bit-exact cocotb testbench for module @@MODULE@@.
+"""
+
+import base64
+import pickle
+import random
+import zlib
+
+import cocotb
+from cocotb.clock import Clock
+from cocotb.triggers import FallingEdge, RisingEdge, Timer
+
+# TODO: make it self-contained by removing the holoso dependency: https://github.com/Zubax/holoso/issues/12
+# Currently it is needed for unpickling.
+import holoso
+
+# Unpickle the opaque model handle and elaborate the runnable simulator the bench drives in lockstep with the DUT.
+_SIM = pickle.loads(zlib.decompress(base64.b64decode("@@BLOB@@"))).elaborate()  # TODO issues/12
+_IN_PORTS = _SIM.inputs  # logical input ports (name + scalar type), in module-port order
+_OUT_PORTS = _SIM.outputs
+
+# An explicit input sequence -- rows of per-input ZKF bits ordered as the input ports -- or None to draw the default
+# random sweep below. The fixed seed makes the default sweep and the back-pressure stalls reproducible.
+_VECTORS = @@VECTORS@@
+_SEED = 0x9E3779B97F4A7C15  # TODO: allow overriding the seed, count, and range via plusargs.
+_DEFAULT_COUNT = 64
+_DEFAULT_RANGE = (-4.0, +4.0)  # small bounded range keeps multi-operation kernels from overflowing into infinities
+_MAX_TRANSACTION_CYCLES = 1 << 20  # out_valid ceiling: well above any real transaction, tripped only by a runaway loop
+
+
+def _output_bits(value):
+    return int(value) if isinstance(value, bool) else value.bits
+
+
+def _input_bits(port, rng, lo, hi):
+    # Encode one random input per its scalar type: a boolean draws a single bit, a float a ZKF-encoded sample.
+    match port.scalar_type:
+        case holoso.BoolType():
+            return rng.randint(0, 1)
+        case holoso.FloatType(fmt=fmt):
+            return fmt.encode(rng.uniform(lo, hi))
+        case other:
+            raise TypeError("unsupported input scalar type: %r" % (other,))
+
+
+def _input_value(port, bits):
+    match port.scalar_type:
+        case holoso.BoolType():
+            return bool(bits)
+        case holoso.FloatType(fmt=fmt):
+            return holoso.FloatValue.from_bits(fmt, bits)
+        case other:
+            raise TypeError("unsupported input scalar type: %r" % (other,))
+
+
+@cocotb.test()
+async def cosim(dut):
+    rng = random.Random(_SEED)
+    if _VECTORS is not None:
+        sequence = _VECTORS
+    else:
+        lo, hi = _DEFAULT_RANGE
+        sequence = [[_input_bits(p, rng, lo, hi) for p in _IN_PORTS] for _ in range(_DEFAULT_COUNT)]
+
+    cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
+    await FallingEdge(dut.clk)
+    dut.rst.value = 1
+    dut.in_valid.value = 0
+    dut.out_ready.value = 0
+    for _ in range(4):
+        await RisingEdge(dut.clk)
+    dut.rst.value = 0
+    await FallingEdge(dut.clk)
+    _SIM.reset()  # the simulator and the DUT are now both idle at pc==0 (in_ready), aligned cycle for cycle from here
+
+    async def lockstep(in_valid, out_ready):
+        # Advance ONE clock on the DUT and the simulator with the identical handshake, then assert they still agree. The
+        # simulator is the cycle-accurate reference, so out_valid asserting on the same cycle is the latency check, and
+        # in_ready agreeing keeps the accept handshake aligned.
+        dut.in_valid.value = 1 if in_valid else 0
+        dut.out_ready.value = 1 if out_ready else 0
+        await RisingEdge(dut.clk)
+        await Timer(1, unit="ns")
+        _SIM.tick(in_valid, out_ready)
+        assert _SIM.out_valid == bool(int(dut.out_valid.value)), "out_valid diverged: model %d dut %d" % (
+            int(_SIM.out_valid),
+            int(dut.out_valid.value),
+        )
+        assert _SIM.in_ready == bool(int(dut.in_ready.value)), "in_ready diverged: model %d dut %d" % (
+            int(_SIM.in_ready),
+            int(dut.in_ready.value),
+        )
+
+    def check_outputs(index):
+        for port, value in zip(_OUT_PORTS, _SIM.output_values):
+            want = _output_bits(value)
+            got = int(getattr(dut, port.name).value)
+            assert got == want, "vector %d port %s: got 0x%x expected 0x%x" % (index, port.name, got, want)
+
+    for index, in_bits in enumerate(sequence):
+        waited = 0
+        while not _SIM.in_ready:  # idle until both can accept; they advance together so they reach it together
+            await lockstep(False, False)
+            waited += 1
+            assert waited < _MAX_TRANSACTION_CYCLES, "vector %d: in_ready not reached" % index
+        # Accept: present the same input bits to the DUT and the simulator, then pulse in_valid for one cycle.
+        for port, bits in zip(_IN_PORTS, in_bits):
+            getattr(dut, "in_" + port.name).value = int(bits)
+        _SIM.set_inputs(*[_input_value(p, bits) for p, bits in zip(_IN_PORTS, in_bits)])
+        await lockstep(True, False)  # accept edge: pc 0 -> 1
+        # Run to out_valid in lockstep. The simulator reaches it on the same cycle as the DUT (the lockstep asserts so
+        # each cycle), which is the cycle-accurate, data-dependent latency check -- no separate prediction needed.
+        waited = 0
+        while not _SIM.out_valid:
+            await lockstep(False, False)
+            waited += 1
+            assert waited < _MAX_TRANSACTION_CYCLES, "vector %d: out_valid not reached within %d cycles" % (
+                index,
+                _MAX_TRANSACTION_CYCLES,
+            )
+        assert int(dut.err_pc.value) == 0, "vector %d: unexpected error at cycle %d" % (index, int(dut.err_pc.value))
+        check_outputs(index)
+        # Random back-pressure: hold out_ready low. out_valid and the outputs must stay stable on both, and neither
+        # advances its persistent state until the transaction is accepted (out_valid && out_ready).
+        for _ in range(rng.randint(0, 3)):
+            assert _SIM.out_valid, "vector %d: simulator dropped out_valid under back-pressure" % index
+            check_outputs(index)
+            await lockstep(False, False)
+        check_outputs(index)
+        await lockstep(False, True)  # accept the output: both advance the persistent state, pc -> 0
+'''
+
+
+@dataclass(frozen=True, slots=True)
+class CocotbOutput:
+    """The cocotb backend's output: one self-contained, self-checking cocotb testbench module."""
+
+    testbench: str
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__}(testbench_bytes={len(self.testbench.encode())})"
+
+
+def _embed_vectors(input_names: list[str], vectors: list[Mapping[str, int]] | None) -> str:
+    """Render the explicit input sequence as a Python literal of input-name-ordered ZKF-bit rows, or ``None``."""
+    if vectors is None:
+        return "None"
+    rows: list[list[int]] = []
+    for index, vector in enumerate(vectors):
+        if missing := [name for name in input_names if name not in vector]:
+            raise ValueError(f"cosim vector {index} is missing inputs {missing}")
+        rows.append([int(vector[name]) for name in input_names])
+    return repr(rows)
+
+
+def generate(model: NumericalModel, vectors: list[Mapping[str, int]] | None = None) -> CocotbOutput:
+    """
+    Build a self-contained cocotb testbench that checks the DUT against the embedded bit-exact model.
+
+    When ``vectors`` is given, each maps an input-port name to its ZKF bits and the bench replays the sequence verbatim
+    (one accepted transaction per vector, state carried across for stateful modules). When it is ``None``, the bench
+    draws a fixed-seed random sweep over a small bounded range instead. Either way the run is fully reproducible.
+    """
+    blob = base64.b64encode(zlib.compress(pickle.dumps(model, pickle.HIGHEST_PROTOCOL))).decode("ascii")
+    testbench = (
+        _TEMPLATE.replace("@@MODULE@@", model.module_name)
+        .replace("@@VECTORS@@", _embed_vectors([port.name for port in model.inputs], vectors))
+        .replace("@@BLOB@@", blob)
+    )
+    return CocotbOutput(testbench=testbench)

holoso-0.1.0/holoso/_backend/html/__init__.py

@@ -0,0 +1,3 @@
+"""The HTML backend: render a self-contained single-page report for a synthesized module."""
+
+from ._html import HtmlOutput as HtmlOutput, generate as generate