arcade.hardware

Stage 3 — Hardware: HLS4ML export, synthesis report parsing, resource estimation, scalability.

class arcade.hardware.BaseHardwareEstimator[source]

Bases: ABC

Interface for hardware resource estimation.

Subclass and decorate with @register_estimator("name").

Example:

@register_estimator("my_estimator")
class MyEstimator(BaseHardwareEstimator):
    def estimate(self, model, **kwargs):
        ...
        return ResourceReport(classifier_name="my_clf", lut=100)
abstractmethod estimate(model, **kwargs)[source]

Estimate hardware resources for a given model.

Parameters:

  • model (Any) – The trained model to estimate resources for.

  • **kwargs (Any) – Estimator-specific options.

Return type:

ResourceReport

Returns:

A ResourceReport with estimated FPGA resources.

name: str = 'base'
class arcade.hardware.AnalyticalEstimator[source]

Bases: BaseHardwareEstimator

Data-driven analytical hardware estimator.

estimate(model, **kwargs)[source]

Estimate hardware resources for a given model.

Parameters:

  • model (Any) – The trained model to estimate resources for.

  • **kwargs (Any) – Estimator-specific options.

Return type:

ResourceReport

Returns:

A ResourceReport with estimated FPGA resources.

name: str = 'analytical'
class arcade.hardware.ResourceReport(classifier_name, lut=None, ff=None, bram=None, dsp=None, latency_cycles=None, latency_ns=None, macs_per_inference=None, clock_period_ns=None, estimated=True, note='')[source]

Bases: object

FPGA resource estimate for a single classifier.

Parameters:

  • classifier_name (str)

  • lut (int | None)

  • ff (int | None)

  • bram (int | None)

  • dsp (int | None)

  • latency_cycles (int | None)

  • latency_ns (float | None)

  • macs_per_inference (int | None)

  • clock_period_ns (float | None)

  • estimated (bool)

  • note (str)

bram: int | None = None
clock_period_ns: float | None = None
dsp: int | None = None
estimated: bool = True
ff: int | None = None
latency_cycles: int | None = None
latency_ns: float | None = None
lut: int | None = None
macs_per_inference: int | None = None
note: str = ''
classifier_name: str
arcade.hardware.register_estimator(name)[source]

Decorator to register a hardware estimator class by name.

Parameters:

name (str)

arcade.hardware.get_estimator(name)[source]

Look up a hardware estimator by registry name or dotted import path.

Return type:

type[BaseHardwareEstimator]

Parameters:

name (str)

arcade.hardware.estimate_resources(model, config=None, *, classifier_name='unknown')[source]

Estimate FPGA resources for a trained classifier.

Dispatches to type-specific parameter sets based on the model type.

Parameters:

  • model (Any) – Trained classifier (NN, hybrid, threshold, sklearn, etc.).

  • config (dict | None) – The hardware section of the ARCADE config (optional).

  • classifier_name (str) – Human-readable name for the report.

Return type:

ResourceReport

Returns:

A ResourceReport with resource estimates.

arcade.hardware.export_hls4ml(model, output_dir, *, backend='Vivado', clock_period=5.0, io_type='io_parallel', reuse_factor=1, precision='ap_fixed<16,6>')[source]

Convert a trained PyTorch model to an HLS4ML project.

Parameters:

  • model (Any) – Trained PyTorch nn.Module.

  • output_dir (Union[str, Path]) – Directory for the generated HLS project.

  • backend (str) – HLS backend ("Vivado" or "Quartus").

  • clock_period (float) – Target clock period in nanoseconds.

  • io_type (str) – "io_parallel" or "io_stream".

  • reuse_factor (int) – Resource reuse factor (higher = smaller area, longer latency).

  • precision (str) – Default fixed-point precision for all layers.

Return type:

Path

Returns:

Path to the generated HLS project directory.

Raises:
arcade.hardware.parse_synth_report(project_dir, *, report_file=None)[source]

Parse a Vivado synthesis report and return key metrics.

Parameters:

  • project_dir (Union[str, Path]) – Path to the HLS4ML / Vivado project directory.

  • report_file (str | None) – Specific report file to parse. If None, auto-detects by searching for common filenames.

Return type:

dict[str, Any]

Returns:

Dict with "lut", "ff", "bram", "dsp", "latency_cycles", "clock_period_ns", "latency_ns", and "report_path".

Raises:

FileNotFoundError – If no report file is found.

arcade.hardware.project_scalability(base_report, qubit_counts, *, base_num_qubits=5, num_levels=2, n_filter_types=1)[source]

Project resource usage to different qubit counts.

Extrapolates from a base measurement or estimate using known scaling relationships:

  • Filter count scales as C(num_levels, 2) * num_qubits * n_filter_types.

  • NN input dim scales linearly with filter count.

  • NN compute (MACs) scales quadratically with input dim for the first hidden layer, linearly for subsequent layers.

  • Threshold/comparator resources scale linearly.

Parameters:

  • base_report (ResourceReport) – Measured or estimated resources at base_num_qubits.

  • qubit_counts (Sequence[int]) – Target qubit counts to project to.

  • base_num_qubits (int) – Qubit count the base_report was measured at.

  • num_levels (int) – Energy levels per qubit.

  • n_filter_types (int) – Number of filter families (1=MF, 2=MF+RMF, 3=MF+RMF+EMF).

Return type:

list[dict[str, Any]]

Returns:

List of dicts with "num_qubits", "lut", "ff", "bram", "dsp", "latency_cycles", "latency_ns", and "scale_factor".

arcade.hardware.project_qubit_scaling(base_report, qubit_counts, *, base_num_qubits=5, num_levels=2, n_filter_types=1)

Project resource usage to different qubit counts.

Extrapolates from a base measurement or estimate using known scaling relationships:

  • Filter count scales as C(num_levels, 2) * num_qubits * n_filter_types.

  • NN input dim scales linearly with filter count.

  • NN compute (MACs) scales quadratically with input dim for the first hidden layer, linearly for subsequent layers.

  • Threshold/comparator resources scale linearly.

Parameters:

  • base_report (ResourceReport) – Measured or estimated resources at base_num_qubits.

  • qubit_counts (Sequence[int]) – Target qubit counts to project to.

  • base_num_qubits (int) – Qubit count the base_report was measured at.

  • num_levels (int) – Energy levels per qubit.

  • n_filter_types (int) – Number of filter families (1=MF, 2=MF+RMF, 3=MF+RMF+EMF).

Return type:

list[dict[str, Any]]

Returns:

List of dicts with "num_qubits", "lut", "ff", "bram", "dsp", "latency_cycles", "latency_ns", and "scale_factor".

class arcade.hardware.DSEPoint(reuse_factor, precision, io_type, lut=None, ff=None, dsp=None, bram=None, latency_ns=None, accuracy=None)[source]

Bases: object

One point in the design space.

Parameters:

  • reuse_factor (int)

  • precision (str)

  • io_type (str)

  • lut (int | None)

  • ff (int | None)

  • dsp (int | None)

  • bram (int | None)

  • latency_ns (float | None)

  • accuracy (float | None)

accuracy: float | None = None
bram: int | None = None
dsp: int | None = None
ff: int | None = None
latency_ns: float | None = None
lut: int | None = None
reuse_factor: int
precision: str
io_type: str
class arcade.hardware.DSEResult(points=<factory>, pareto_optimal=<factory>, best_accuracy=None, best_resources=None, best_balanced=None)[source]

Bases: object

Result of design-space exploration.

Parameters:
best_accuracy: DSEPoint | None = None
best_balanced: DSEPoint | None = None
best_resources: DSEPoint | None = None
points: list[DSEPoint]
pareto_optimal: list[DSEPoint]
arcade.hardware.explore_design_space(model, train_features, train_labels, test_features, test_labels, *, reuse_factors=None, precisions=None, io_types=None, target_fpga='xc7z020', clock_period_ns=5.0)[source]

Sweep reuse_factor x precision x io_type and estimate resources.

For each combination, estimates FPGA resources analytically. When HLS4ML is available, uses actual synthesis estimates.

Return type:

DSEResult

Parameters: