Optimiser API¶

The sc_neurocore.optimizer package exposes two optimisation surfaces:

fit_to_target(...) for deterministic resource fitting against FPGA target budgets.
SurrogateSCOptimizer for ML-guided stochastic-computing compiler choices using generated analytical design points plus optional measured observations.

It also exposes strict evidence loaders so benchmark and synthesis reports can feed the surrogate without fabricating missing LUT, power, latency, or accuracy values.

Deterministic Resource Fitting¶

Use fit_to_target when you have layer dimensions and weights and want the legacy prune / quantise / bitstream-length loop to reduce estimated FPGA resource use:

Python

import numpy as np

from sc_neurocore.optimizer import fit_to_target

weights = [np.ones((32, 16), dtype=np.float32)]
result = fit_to_target(
    layer_sizes=[(32, 16)],
    weights=weights,
    target="ice40",
    initial_bitstream_length=256,
)

print(result.summary())

The result reports whether the design fits, final estimated LUT use, selected bitstream length, sparsity, and each optimisation step.

Surrogate-Guided SC Optimisation¶

Use SurrogateSCOptimizer when the compiler must choose per-layer stochastic computing settings under LUT, power, and latency pressure:

Python

from sc_neurocore.optimizer import SurrogateSCOptimizer, TargetHardwareProfile
from sc_neurocore.optimizer.sc_optimizer import HardwareBudget, LayerProfile

target = TargetHardwareProfile(
    name="ice40-low-power",
    budget=HardwareBudget(max_luts=7680, max_power_mw=250.0, max_latency_cycles=4096),
)
network = [
    LayerProfile(id="encoder", mac_count=256, is_critical_path=True),
    LayerProfile(id="decoder", mac_count=128),
]

report = SurrogateSCOptimizer(target).optimise(network)

The report contains selected bitstream length, decorrelator, precision, LFSR polynomial, estimated LUTs, power, latency, utility score, and any rejected layers.

Measured Evidence¶

Measured observations are optional but preferred. The loader accepts JSON payloads with observations, benchmark_observations, layers, runs, or results records and raises ObservationLoadError when required fields are missing. Numeric metrics must be finite, non-negative numbers; integer fields such as mac_count, bitstream_length, precision_bits, luts_used, and latency_cycles reject booleans and fractional values.

Python

from sc_neurocore.optimizer import load_observations

observations = load_observations("benchmarks/results/fpga_power_observations.json")

For raw Vivado or Quartus reports, use the package helper:

Python

from sc_neurocore.optimizer import build_payload_from_reports, write_payload

payload = build_payload_from_reports(
    design_path="build/network_design.json",
    utilisation_path="build/vivado_utilisation.rpt",
    power_path="build/vivado_power.rpt",
    timing_path="build/vivado_timing.rpt",
    accuracy_score=0.991,
    clock_mhz=100.0,
    inferences_per_run=1,
)
write_payload(payload, "build/synthesis_observations.json")

The same flow is available from the CLI:

Bash

sc-neurocore collect-synthesis \
  --design build/network_design.json \
  --utilisation build/vivado_utilisation.rpt \
  --power build/vivado_power.rpt \
  --timing build/vivado_timing.rpt \
  --accuracy-score 0.991 \
  --clock-mhz 100 \
  --inferences-per-run 1 \
  --out build/synthesis_observations.json

Energy fields are computed only when both clock_mhz and inferences_per_run are provided. Vendor reports remain the evidence source; the helper does not run synthesis or invent measurements.

`sc_neurocore.optimizer` ¶

Automatically compress and tune SNNs for target hardware.

`ObservationLoadError` ¶

Bases: ValueError

Raised when a benchmark/synthesis observation cannot be trusted.

Source code in src/sc_neurocore/optimizer/observation_loader.py

Python
class ObservationLoadError(ValueError):
    """Raised when a benchmark/synthesis observation cannot be trusted."""

`SynthesisFeedbackResult` `dataclass` ¶

Result of one measured-evidence optimiser feedback pass.

Source code in src/sc_neurocore/optimizer/feedback_loop.py

Python
@dataclass(frozen=True)
class SynthesisFeedbackResult:
    """Result of one measured-evidence optimiser feedback pass."""

    evidence_payload: dict[str, Any]
    observations: tuple[BenchmarkObservation, ...]
    report: SurrogateOptimizerReport

`OptimizationResult` `dataclass` ¶

Result of the resource optimization process.

Source code in src/sc_neurocore/optimizer/resource_optimizer.py

Python
@dataclass
class OptimizationResult:
    """Result of the resource optimization process."""

    fits: bool
    target: str
    final_luts: int
    target_luts: int
    utilization_pct: float
    final_bitstream_length: int
    final_sparsity: float
    steps: list[OptimizationStep] = field(default_factory=list)
    optimized_weights: list[np.ndarray] = field(default_factory=list, repr=False)

    def summary(self) -> str:
        lines = [
            f"Resource Optimization: {self.target}",
            f"  Fits: {'YES' if self.fits else 'NO'}",
            f"  LUTs: {self.final_luts:,} / {self.target_luts:,} ({self.utilization_pct:.1f}%)",
            f"  Bitstream length: {self.final_bitstream_length}",
            f"  Sparsity: {self.final_sparsity:.1%}",
            f"  Steps taken: {len(self.steps)}",
        ]
        for s in self.steps:
            lines.append(f"    {s.action}: {s.luts_before:,} -> {s.luts_after:,} LUTs")
        return "\n".join(lines)

`BenchmarkObservation` `dataclass` ¶

Measured or externally supplied design-point observation.

The optimiser treats these as higher-priority training points than its analytical generated points. Callers should only pass observations that come from real benchmark or synthesis outputs.