Skip to content

Hardware Drivers

Module: sc_neurocore.drivers Source: src/sc_neurocore/drivers/ — 4 files, 399 LOC, __tier__ = "research" Status (v3.15.35): PYNQ-Z2 FPGA driver works in EMULATION mode and correctly fails fast in HARDWARE mode without PYNQ. PhysicalTwinBridge now exposes an honest deterministic EMULATION backend and an explicit JSON-line TCP backend for hardware-twin services. verify_hardware_link uses normal PYTHONPATH resolution for optional sister-repo probes and does not mutate sys.path.

This page covers the three public symbols that drivers expose, what each one actually does, and what each one only claims to do.

1. Public surface

sc_neurocore.drivers.__init__ re-exports 3 symbols and declares the research tier:

Symbol Source file Role
SC_NeuroCore_Driver sc_neurocore_driver.py PYNQ-Z2 FPGA overlay + AXI-Lite register access
PhysicalTwinBridge physical_twin.py Deterministic emulation bridge or explicit TCP hardware-twin client
verify_link verify_hardware_link.py Diagnostic CLI that probes FPGA, Evo 2, Opentrons OT-2

Module-level constants: - __tier__ = "research" — flag that the module is not stable API. - RealityHardwareError(ImportError) — raised when hardware mode is requested but PYNQ libraries are missing.

2. SC_NeuroCore_Driver

Python
class SC_NeuroCore_Driver:
    def __init__(
        self,
        bitstream_path: str = "sc_neurocore.bit",
        mode: str = "HARDWARE",
    ) -> None: ...

Driver for the sc-neurocore FPGA overlay on PYNQ-Z2. Two modes:

  • mode="HARDWARE" (default) — imports pynq.Overlay, loads the .bit file, and verifies the bitstream contains the scpn_layer_1_0 IP block. Raises RealityHardwareError on any of:
  • PYNQ Python library missing
  • bitstream file not at the given path or at /usr/local/lib/pynq/overlays/sc_neurocore/<bitstream>
  • loaded overlay does not have the expected scpn_layer_1_0 IP (wrapped as RealityHardwareError)
  • mode="EMULATION" — logs a warning and continues without touching any hardware. Used for development on x86 workstations.

Any other mode raises ValueError.

2.1 write_layer_params(layer_id, params)

Writes gain and/or threshold parameters to the named layer's AXI-Lite registers in fixed-point Q16.16:

Parameter Register offset Encoding
gain 0x10 int(value * 65536)
threshold 0x14 int(value * 65536)

In EMULATION mode the call is a logger.debug no-op. In HARDWARE mode it walks the overlay attribute namespace via getattr(overlay, f"scpn_layer_{layer_id}_0") and raises ValueError if the IP block is absent.

The Q16.16 encoding here differs from the Q8.8 used elsewhere in sc-neurocore (compiler, network/export). Documented but worth flagging if FPGA register IPs are migrated to Q8.8 in the future.

2.2 run_step(input_vector)

In HARDWARE mode raises NotImplementedError ("DMA transfer requires PYNQ overlay") — i.e. no real DMA path is wired yet.

In EMULATION mode returns self._rng.random(16) — uses the per-instance RNG seeded in __init__ (default seed=42). Two drivers built with the same seed produce identical output sequences. Fixed by task #29; see §8.2 for the regression-test breakdown.

2.3 Module-level test entry point

if __name__ == "__main__" at sc_neurocore_driver.py:115-123 runs a strict reality-check: instantiate in HARDWARE mode, expect RealityHardwareError on x86. Used as a quick python -m sc_neurocore.drivers.sc_neurocore_driver smoke test.

3. PhysicalTwinBridge

PhysicalTwinBridge keeps the historical class name for API compatibility, but it no longer pretends a mock is physical hardware. It has two explicit modes:

  • mode="EMULATION" (default) — deterministic local development mode. It uses a per-instance numpy.random.default_rng(seed) noise source, sets connected=True only for the local emulation backend, and writes no stdout on construction or divergence.
  • mode="TCP" — real hardware-twin client mode. Each sync_step(...) opens a bounded TCP connection to (ip, port), sends one compact JSON-line request, and requires a JSON-line reply containing numeric v_mem.

Constructor:

Python
class PhysicalTwinBridge:
    def __init__(
        self,
        ip: str = "192.168.2.99",
        port: int = 5000,
        *,
        mode: str = "EMULATION",
        timeout_s: float = 1.0,
        seed: int = 42,
        noise_sigma: float = 0.01,
        divergence_threshold: float = 0.1,
    ) -> None: ...

TCP request payload:

Python
{"spike":1,"v_mem":0.5}

TCP reply payload:

Python
{"v_mem": 0.875}

Malformed replies raise ValueError. Connection failures raise ConnectionError. Divergence warnings go through module logging, not stdout, so library callers can silence or route them.

Regression coverage: tests/test_pynq_driver.py::TestPhysicalTwinBridge verifies no stdout side effects, deterministic emulation, the compact JSON-line TCP contract, and fail-closed malformed hardware replies.

verify_hardware_link.py exposes a single function verify_link() that runs three sequential checks:

Step Target Mechanism Failure mode
1/3 PYNQ-Z2 / FPGA bitstream SC_NeuroCore_Driver(mode="HARDWARE") RealityHardwareError → "Simulation Mode" message
2/3 Evo 2 genomic interface from scpn_evo2_real_interface import Evo2RealInterface then evo.connect() ImportError → "module not found"; OSError/ConnectionError → "Server unreachable"
3/3 Opentrons OT-2 robot from scpn_opentrions_verify import OpentronsVerifier then ot2.ping() ImportError → "module not found"; OSError → "ERROR"

4.1 Cross-repo sys.path.append removed (FIXED by task #31)

The previous version mutated sys.path to reach into a sibling SCPN-CODEBASE/HolonomicAtlas/src/interfaces/ directory. That behaviour was fragile (it assumed the GOTM monorepo layout) and violated the principle that library code shouldn't manipulate import paths.

verify_link() now imports scpn_evo2_real_interface and scpn_opentrions_verify via standard PYTHONPATH resolution. If the modules are not on the path the probe reports "FAILURE: <module> not on PYTHONPATH" cleanly without changing import state. The probe also accepts extras: bool = True (default) — pass extras=False to skip both sibling-repo probes and check only the FPGA subsystem.

Regression coverage: tests/test_pynq_driver.py::TestVerifyHardwareLink (4 tests): extras=False FPGA-only output, extras=True full output, default is True, verify_link does not mutate sys.path.

4.2 Module-level test entry point

if __name__ == "__main__" at line 71-72 runs verify_link(), so python -m sc_neurocore.drivers.verify_hardware_link produces the diagnostic table as a console output.

5. RealityHardwareError

Python
class RealityHardwareError(ImportError):
    """Raised when physical hardware is required but missing."""

Subclass of ImportError, raised by _connect_to_fpga when: - PYNQ Python library not importable, or - bitstream file not found at given path or fallback path, or - bitstream loaded but lacks the expected IP block, or - any OSError / RuntimeError during overlay construction.

The strict reality-check pattern means callers can try / except RealityHardwareError to detect non-FPGA hosts and switch to EMULATION cleanly.

6. Pipeline wiring

Surface How it's wired Verifier
from sc_neurocore.drivers import SC_NeuroCore_Driver, ... drivers/__init__.py:12-14 tests/test_pynq_driver.py
HARDWARE mode dispatch _connect_to_fpga in __init__ test_driver_hardware_mode_fails_without_fpga, test_driver_hardware_mode_uses_install_fallback_bitstream, test_driver_hardware_mode_rejects_overlay_without_expected_ip, test_driver_hardware_mode_wraps_overlay_runtime_errors
EMULATION mode dispatch logger warning + skip hardware path test_driver_emulation_mode
write_layer_params AXI-Lite path getattr(overlay, ...), Q16.16 register writes test_driver_write_layer_params, test_driver_write_layer_params_hardware_q16_16_encoding, test_driver_write_layer_params_hardware_rejects_missing_layer
run_step EMULATION return per-instance numpy.random.default_rng(seed) test_driver_run_step, TestRunStepDeterminism
RealityHardwareError propagation raised on PYNQ import / file / IP failures test_driver_hardware_mode_fails_without_fpga
PhysicalTwinBridge EMULATION/TCP boundary deterministic local backend plus JSON-line TCP exchange TestPhysicalTwinBridge
verify_link CLI if __name__ == "__main__" invokes it TestVerifyHardwareLink covers callable behaviour

7. Audit (7-point checklist)

# Dimension Status Detail
1 Pipeline wiring ✅ PASS All 3 symbols re-exported; HARDWARE/EMULATION dispatch tested
2 Multi-angle tests ✅ PASS SC_NeuroCore_Driver, verify_link, and PhysicalTwinBridge all have focused tests covering emulation, failure boundaries, deterministic behaviour, and TCP contract handling.
3 Rust path N/A I/O + AXI-Lite shim; no compute kernel
4 Benchmarks N/A Hardware register writes and bounded TCP I/O; no meaningful benchmark without physical hardware
5 Performance docs N/A Same as above
6 Documentation page ✅ PASS This page
7 Rules followed ✅ PASS PhysicalTwinBridge now separates deterministic emulation from real TCP hardware-twin mode, run_step(EMULATION) uses a per-instance RNG, verify_hardware_link.py no longer mutates sys.path, the undocumented physical_twin.py type-ignore marker was removed, and the optional PYNQ import uses a narrow type: ignore[import-not-found]. SPDX header on every file ✅.

Net: driver public-surface audit is now PASS for the locally testable x86 scope. HARDWARE-mode happy-path evidence still requires a physical PYNQ-Z2 board and remains part of the separate physical validation backlog.

8. Known issues (for the implementation)

8.1 PhysicalTwinBridge TCP contract (FIXED by task #30)

PhysicalTwinBridge no longer sets physical connection state without I/O. EMULATION mode is explicit and deterministic; TCP mode uses a bounded JSON-line contract with fail-closed malformed-reply handling.

8.2 run_step EMULATION RNG (FIXED by task #29)

SC_NeuroCore_Driver.__init__ now accepts seed: int = 42 and constructs self._rng = np.random.default_rng(seed). The EMULATION run_step returns self._rng.random(16) instead of np.random.rand(16), so two drivers built with the same seed produce bitwise-identical output sequences regardless of the global numpy RNG state.

Regression coverage: tests/test_pynq_driver.py::TestRunStepDeterminism (5 tests): same-seed first call, same-seed 50-step sequence, distinct seeds differ, global numpy seed does not leak in, default seed is 42.

8.3 verify_hardware_link.py sys.path.append (FIXED by task #31)

verify_link() no longer mutates sys.path. It accepts an extras: bool = True parameter — pass extras=False to skip the two sibling-repo probes and check only the FPGA subsystem. See §4.1.

8.4 Optional PYNQ import typing boundary (FIXED)

sc_neurocore_driver.py imports optional PYNQ symbols only inside HARDWARE-mode connection setup. The import keeps # noqa: F401 because allocate is intentionally imported with the PYNQ runtime surface, and now uses the narrow # type: ignore[import-not-found] marker required for hosts where PYNQ is unavailable.

Regression coverage: tests/test_pynq_driver.py::TestDriverSourceHygiene asserts that the driver source keeps the narrow marker and does not reintroduce the old broad type: ignore form.

8.5 Q16.16 in the FPGA driver vs Q8.8 elsewhere (DOCUMENTED)

write_layer_params encodes parameters as int(value * 65536), which is Q16.16 (16 integer + 16 fractional bits). The compiler (equation_compiler.py) uses Q8.8. If the FPGA register IPs are re-spun to Q8.8, this multiplication needs to change to * 256. Document the Q-format choice in the IP-block contract.

Regression coverage: test_driver_write_layer_params_hardware_q16_16_encoding constructs a fake overlay and verifies the HARDWARE path writes gain to offset 0x10 and threshold to offset 0x14 using Q16.16 integer values. test_driver_write_layer_params_hardware_rejects_missing_layer verifies that absent layer IPs fail closed.

9. Tests

Bash
PYTHONPATH=src python3 -m pytest tests/test_pynq_driver.py -v

Coverage breakdown:

Test What it checks
test_driver_emulation_mode EMULATION mode constructs without raising
test_driver_write_layer_params EMULATION path no-ops cleanly with both gain and threshold
test_driver_write_layer_params_hardware_q16_16_encoding HARDWARE path writes Q16.16 gain and threshold values to the expected AXI-Lite offsets
test_driver_write_layer_params_hardware_rejects_missing_layer HARDWARE path raises when the target layer IP is absent
test_driver_run_step EMULATION returns shape-(16,) ndarray
test_driver_hardware_mode_fails_without_fpga HARDWARE on x86 raises RealityHardwareError
test_driver_hardware_mode_uses_install_fallback_bitstream Missing local bitstream resolves to installed PYNQ overlay path and loads that path
test_driver_hardware_mode_rejects_overlay_without_expected_ip Loaded overlays without scpn_layer_1_0 fail closed as RealityHardwareError
test_driver_hardware_mode_wraps_overlay_runtime_errors Overlay loader runtime failures are wrapped as RealityHardwareError
test_driver_invalid_mode mode="WHATEVER" raises ValueError
TestRunStepDeterminism Same-seed reproducibility, sequence reproducibility, seed separation, global RNG isolation, default seed
TestVerifyHardwareLink FPGA-only probe mode, full probe mode, default extras behaviour, no sys.path mutation
TestPhysicalTwinBridge No stdout side effects, deterministic emulation, compact JSON-line TCP contract, malformed-reply failure

Not covered:

  • HARDWARE mode happy path — requires actual PYNQ-Z2; cannot be exercised on x86 (test_driver_hardware_mode_fails_without_fpga is the inverse)

10. References

  • Xilinx PYNQ — pynq.io — Python overlay framework for Zynq-class FPGAs.
  • TUL PYNQ-Z2 board — board spec the FPGA driver is written against.
  • AXI-Lite specification — Arm IHI 0022 — register-mapped peripheral protocol used for write_layer_params.

Internal:

11. Auto-rendered API

sc_neurocore.drivers

sc_neurocore.drivers -- Tier: research (experimental / research).

SC_NeuroCore_Driver

Primary driver for the sc-neurocore FPGA overlay on PYNQ-Z2.

This driver enforces 'Reality Checks'. It will NOT run on standard x86 CPUs unless explicitly in 'EMULATION' mode.

Source code in src/sc_neurocore/drivers/sc_neurocore_driver.py
Python
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
class SC_NeuroCore_Driver:
    """
    Primary driver for the sc-neurocore FPGA overlay on PYNQ-Z2.

    This driver enforces 'Reality Checks'. It will NOT run on standard x86 CPUs
    unless explicitly in 'EMULATION' mode.
    """

    def __init__(
        self,
        bitstream_path: str = "sc_neurocore.bit",
        mode: str = "HARDWARE",
        seed: int = 42,
    ) -> None:
        """Construct a driver in HARDWARE or EMULATION mode.

        Parameters
        ----------
        bitstream_path : str
            Path to the ``.bit`` file for HARDWARE mode.
        mode : str
            ``'HARDWARE'`` or ``'EMULATION'``.
        seed : int
            Per-instance RNG seed used by EMULATION ``run_step`` so
            successive calls are deterministic given the same seed.
            Two drivers built with the same seed produce identical
            output sequences.
        """
        self.mode = mode
        self.overlay = None
        self.dma = None
        self.bitstream_path = bitstream_path
        self._rng = np.random.default_rng(seed)

        if self.mode == "HARDWARE":
            self._connect_to_fpga()
        elif self.mode == "EMULATION":
            logger.warning(
                "Running in EMULATION mode. Results may not reflect quantum stochasticity."
            )
        else:
            raise ValueError("Invalid mode. Use 'HARDWARE' or 'EMULATION'.")

    def _connect_to_fpga(self) -> None:
        """
        Attempts to load the PYNQ libraries and flash the bitstream.
        """
        try:
            from pynq import Overlay, allocate  # type: ignore[import-not-found]  # noqa: F401

            if not os.path.exists(self.bitstream_path):
                # Look in standard install location if not local
                fallback_path = f"/usr/local/lib/pynq/overlays/sc_neurocore/{self.bitstream_path}"
                if os.path.exists(fallback_path):
                    self.bitstream_path = fallback_path
                else:
                    raise FileNotFoundError(f"Bitstream not found at {self.bitstream_path}")

            logger.info(f"Loading bitstream: {self.bitstream_path}")
            self.overlay = Overlay(self.bitstream_path)

            # Check for specific IP blocks to verify it's the right bitstream
            if not hasattr(self.overlay, "scpn_layer_1_0"):
                from sc_neurocore.exceptions import SCHardwareError

                raise SCHardwareError("Loaded bitstream does not contain SCPN Layer 1 IP.")

            logger.info("FPGA Overlay loaded successfully.")

        except ImportError:
            logger.error("PYNQ library not found.")
            raise RealityHardwareError(
                "CRITICAL: PYNQ library missing. This code must run on a Xilinx Zynq SoC (PYNQ-Z2/Z1). "
                "If you are on x86, set mode='EMULATION'."
            )
        except (FileNotFoundError, OSError, RuntimeError) as e:
            logger.error(f"FPGA Connection Failed: {e}")
            raise RealityHardwareError(f"Hardware initialization failed: {e}")

    def write_layer_params(self, layer_id: int, params: dict[str, float]) -> None:
        """
        Writes parameters to a specific layer's AXI-Lite registers.
        """
        if self.mode == "EMULATION":
            logger.debug(f"Emulating write to Layer {layer_id}: {params}")
            return

        # Hardware implementation
        layer_ip = getattr(self.overlay, f"scpn_layer_{layer_id}_0", None)
        if not layer_ip:
            raise ValueError(f"Layer {layer_id} not found in hardware.")

        # Example register map (offset 0x10 = gain, 0x14 = threshold)
        if "gain" in params:
            layer_ip.write(0x10, int(params["gain"] * 65536))  # Fixed point
        if "threshold" in params:
            layer_ip.write(0x14, int(params["threshold"] * 65536))

    def run_step(self, input_vector: object) -> np.ndarray[Any, Any]:
        """
        Executes one integration step on the FPGA.

        EMULATION mode returns a 16-element pseudo-random vector from
        the per-instance RNG seeded in ``__init__``. Two drivers built
        with the same seed produce identical sequences. HARDWARE mode
        is not yet implemented (DMA transfer requires PYNQ overlay).
        """
        if self.mode == "EMULATION":
            # Deterministic mock — uses per-instance RNG, not global numpy.
            return self._rng.random(16)

        raise NotImplementedError(
            "HARDWARE DMA transfer requires PYNQ overlay. Use mode='EMULATION' for development."
        )

__init__(bitstream_path='sc_neurocore.bit', mode='HARDWARE', seed=42)

Construct a driver in HARDWARE or EMULATION mode.

Parameters

bitstream_path : str Path to the .bit file for HARDWARE mode. mode : str 'HARDWARE' or 'EMULATION'. seed : int Per-instance RNG seed used by EMULATION run_step so successive calls are deterministic given the same seed. Two drivers built with the same seed produce identical output sequences.

Source code in src/sc_neurocore/drivers/sc_neurocore_driver.py
Python
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def __init__(
    self,
    bitstream_path: str = "sc_neurocore.bit",
    mode: str = "HARDWARE",
    seed: int = 42,
) -> None:
    """Construct a driver in HARDWARE or EMULATION mode.

    Parameters
    ----------
    bitstream_path : str
        Path to the ``.bit`` file for HARDWARE mode.
    mode : str
        ``'HARDWARE'`` or ``'EMULATION'``.
    seed : int
        Per-instance RNG seed used by EMULATION ``run_step`` so
        successive calls are deterministic given the same seed.
        Two drivers built with the same seed produce identical
        output sequences.
    """
    self.mode = mode
    self.overlay = None
    self.dma = None
    self.bitstream_path = bitstream_path
    self._rng = np.random.default_rng(seed)

    if self.mode == "HARDWARE":
        self._connect_to_fpga()
    elif self.mode == "EMULATION":
        logger.warning(
            "Running in EMULATION mode. Results may not reflect quantum stochasticity."
        )
    else:
        raise ValueError("Invalid mode. Use 'HARDWARE' or 'EMULATION'.")

write_layer_params(layer_id, params)

Writes parameters to a specific layer's AXI-Lite registers.

Source code in src/sc_neurocore/drivers/sc_neurocore_driver.py
Python
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def write_layer_params(self, layer_id: int, params: dict[str, float]) -> None:
    """
    Writes parameters to a specific layer's AXI-Lite registers.
    """
    if self.mode == "EMULATION":
        logger.debug(f"Emulating write to Layer {layer_id}: {params}")
        return

    # Hardware implementation
    layer_ip = getattr(self.overlay, f"scpn_layer_{layer_id}_0", None)
    if not layer_ip:
        raise ValueError(f"Layer {layer_id} not found in hardware.")

    # Example register map (offset 0x10 = gain, 0x14 = threshold)
    if "gain" in params:
        layer_ip.write(0x10, int(params["gain"] * 65536))  # Fixed point
    if "threshold" in params:
        layer_ip.write(0x14, int(params["threshold"] * 65536))

run_step(input_vector)

Executes one integration step on the FPGA.

EMULATION mode returns a 16-element pseudo-random vector from the per-instance RNG seeded in __init__. Two drivers built with the same seed produce identical sequences. HARDWARE mode is not yet implemented (DMA transfer requires PYNQ overlay).

Source code in src/sc_neurocore/drivers/sc_neurocore_driver.py
Python
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def run_step(self, input_vector: object) -> np.ndarray[Any, Any]:
    """
    Executes one integration step on the FPGA.

    EMULATION mode returns a 16-element pseudo-random vector from
    the per-instance RNG seeded in ``__init__``. Two drivers built
    with the same seed produce identical sequences. HARDWARE mode
    is not yet implemented (DMA transfer requires PYNQ overlay).
    """
    if self.mode == "EMULATION":
        # Deterministic mock — uses per-instance RNG, not global numpy.
        return self._rng.random(16)

    raise NotImplementedError(
        "HARDWARE DMA transfer requires PYNQ overlay. Use mode='EMULATION' for development."
    )

PhysicalTwinBridge

Synchronise software neuron state with an explicit twin backend.

mode="EMULATION" is a deterministic local noise model for development and CI. mode="TCP" opens a JSON-line request/response connection for a real hardware-twin service. The class never marks itself connected to physical hardware unless a TCP exchange actually succeeds.

Source code in src/sc_neurocore/drivers/physical_twin.py
Python
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class PhysicalTwinBridge:
    """Synchronise software neuron state with an explicit twin backend.

    ``mode="EMULATION"`` is a deterministic local noise model for development
    and CI. ``mode="TCP"`` opens a JSON-line request/response connection for a
    real hardware-twin service. The class never marks itself connected to
    physical hardware unless a TCP exchange actually succeeds.
    """

    def __init__(
        self,
        ip: str = "192.168.2.99",
        port: int = 5000,
        *,
        mode: str = "EMULATION",
        timeout_s: float = 1.0,
        seed: int = 42,
        noise_sigma: float = 0.01,
        divergence_threshold: float = 0.1,
    ) -> None:
        mode = mode.upper()
        if mode not in {"EMULATION", "TCP"}:
            raise ValueError("PhysicalTwinBridge mode must be 'EMULATION' or 'TCP'")
        if timeout_s <= 0:
            raise ValueError("timeout_s must be positive")
        if noise_sigma < 0:
            raise ValueError("noise_sigma must be non-negative")
        if divergence_threshold <= 0:
            raise ValueError("divergence_threshold must be positive")

        self.ip = ip
        self.port = port
        self.mode = mode
        self.timeout_s = timeout_s
        self.noise_sigma = noise_sigma
        self.divergence_threshold = divergence_threshold
        self.connected = mode == "EMULATION"
        self._rng = np.random.default_rng(seed)

    def sync_step(self, sw_v_mem: float, sw_spike: int) -> float:
        """Send software state and return the twin membrane voltage."""
        if self.mode == "EMULATION" and not self.connected:
            return float(sw_v_mem)
        if self.mode == "TCP":
            return self._sync_step_tcp(sw_v_mem, sw_spike)

        hw_v_mem = sw_v_mem + float(self._rng.normal(0.0, self.noise_sigma))
        self._log_divergence(sw_v_mem, hw_v_mem)
        return hw_v_mem

    def _sync_step_tcp(self, sw_v_mem: float, sw_spike: int) -> float:
        request = (
            json.dumps(
                {"v_mem": float(sw_v_mem), "spike": int(sw_spike)},
                separators=(",", ":"),
                sort_keys=True,
            ).encode("utf-8")
            + b"\n"
        )

        try:
            with socket.create_connection((self.ip, self.port), timeout=self.timeout_s) as sock:
                sock.sendall(request)
                response = next(sock.makefile("r", encoding="utf-8"))
        except StopIteration as exc:
            self.connected = False
            raise ConnectionError("hardware twin closed connection without a reply") from exc
        except OSError as exc:
            self.connected = False
            raise ConnectionError(f"hardware twin connection failed: {exc}") from exc

        hw_v_mem = self._parse_reply(response)
        self.connected = True
        self._log_divergence(sw_v_mem, hw_v_mem)
        return hw_v_mem

    @staticmethod
    def _parse_reply(response: str) -> float:
        try:
            payload: Any = json.loads(response)
        except json.JSONDecodeError as exc:
            raise ValueError("hardware twin reply is not valid JSON") from exc

        value = payload.get("v_mem") if isinstance(payload, dict) else None
        if not isinstance(value, int | float):
            raise ValueError("hardware twin reply missing numeric 'v_mem'")
        return float(value)

    def _log_divergence(self, sw_v_mem: float, hw_v_mem: float) -> None:
        diff = abs(sw_v_mem - hw_v_mem)
        if diff > self.divergence_threshold:
            logger.warning(
                "hardware twin divergence detected: software_v_mem=%.6f hardware_v_mem=%.6f diff=%.6f",
                sw_v_mem,
                hw_v_mem,
                diff,
            )

sync_step(sw_v_mem, sw_spike)

Send software state and return the twin membrane voltage.

Source code in src/sc_neurocore/drivers/physical_twin.py
Python
60
61
62
63
64
65
66
67
68
69
def sync_step(self, sw_v_mem: float, sw_spike: int) -> float:
    """Send software state and return the twin membrane voltage."""
    if self.mode == "EMULATION" and not self.connected:
        return float(sw_v_mem)
    if self.mode == "TCP":
        return self._sync_step_tcp(sw_v_mem, sw_spike)

    hw_v_mem = sw_v_mem + float(self._rng.normal(0.0, self.noise_sigma))
    self._log_divergence(sw_v_mem, hw_v_mem)
    return hw_v_mem

Run the hardware-link diagnostic CLI.

Parameters

extras : bool Run the optional Evo 2 + Opentrons probes when True (default). Set to False to only check the FPGA subsystem; skips the imports of sibling-repo modules.

Source code in src/sc_neurocore/drivers/verify_hardware_link.py
Python
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def verify_link(extras: bool = True) -> None:
    """Run the hardware-link diagnostic CLI.

    Parameters
    ----------
    extras : bool
        Run the optional Evo 2 + Opentrons probes when True
        (default). Set to False to only check the FPGA subsystem;
        skips the imports of sibling-repo modules.
    """
    n_steps = 3 if extras else 1
    print("=" * 60)
    print("SCPN HARDWARE LINK DIAGNOSTIC TOOL")
    print("=" * 60)

    print(f"\n[1/{n_steps}] Checking FPGA Subsystem (Sector B)...")
    try:
        SC_NeuroCore_Driver(mode="HARDWARE")
        print(">> SUCCESS: PYNQ-Z2 Detected. Bitstream loaded.")
    except RealityHardwareError:
        print(">> FAILURE: PYNQ Hardware not found. (Expected if on x86 Dev Workstation)")
        print(">> NOTE: This implies we are in 'Simulation Mode'.")
    except (OSError, RuntimeError) as e:
        print(f">> ERROR: Unexpected failure: {e}")

    if not extras:
        print("\n" + "=" * 60)
        print("DIAGNOSTIC COMPLETE (FPGA only; extras=False)")
        print("=" * 60)
        return

    print(f"\n[2/{n_steps}] Checking Genomic Interface (Layer 6)...")
    # Import via standard PYTHONPATH resolution. The sibling-repo
    # interface module must be on the path; if not, ImportError
    # falls through to the failure message.
    try:
        from scpn_evo2_real_interface import Evo2RealInterface

        evo = Evo2RealInterface()
        evo.connect()  # Will fail if no server
    except ImportError:
        print(
            ">> FAILURE: scpn_evo2_real_interface not on PYTHONPATH "
            "(install or add SCPN-CODEBASE/HolonomicAtlas/src/interfaces "
            "to PYTHONPATH for this probe)."
        )
    except (OSError, ConnectionError, RuntimeError) as e:
        print(f">> WARNING: Evo 2 Server unreachable ({e}).")

    print(f"\n[3/{n_steps}] Checking Robotics Link (Layer 12)...")
    try:
        from scpn_opentrions_verify import OpentronsVerifier

        ot2 = OpentronsVerifier()
        if ot2.ping():
            print(">> SUCCESS: Opentrons OT-2 Online.")
        else:
            print(">> FAILURE: Robot offline.")
    except ImportError:
        print(
            ">> FAILURE: scpn_opentrions_verify not on PYTHONPATH "
            "(install the Opentrons verifier package for this probe)."
        )
    except (OSError, RuntimeError) as e:
        print(f">> ERROR: {e}")

    print("\n" + "=" * 60)
    print("DIAGNOSTIC COMPLETE")
    print("=" * 60)