Solvers¶

Combinatorial optimization via SC-native Ising machines.

StochasticIsingGraph — Quantum-inspired Ising solver. Spins S_i in {-1, +1} (mapped to 0/1 for SC). Energy: E = -Sum(J_ij * S_i * S_j) - Sum(h_i * S_i). Finds minimum-energy configuration via simulated annealing with SC arithmetic.

Maps to SC hardware: spin products = AND gates, energy accumulation = popcount.

Python

import numpy as np
from sc_neurocore.solvers import StochasticIsingGraph

J = np.random.randn(10, 10)
J = (J + J.T) / 2
np.fill_diagonal(J, 0)
solver = StochasticIsingGraph(num_spins=10, J=J)
solution = solver.solve(n_steps=1000)

`sc_neurocore.solvers.ising` ¶

Quantum-inspired Ising machine solver with stochastic Metropolis annealing.

`StochasticIsingGraph` `dataclass` ¶

Quantum-Inspired Ising Machine Solver.

Spins S_i in {-1, 1} (mapped to 0, 1 for SC). Energy E = -Sum(J_ij * S_i * S_j) - Sum(h_i * S_i). Goal: Find configuration that minimizes E.

Source code in src/sc_neurocore/solvers/ising.py

Python
@dataclass
class StochasticIsingGraph:
    """
    Quantum-Inspired Ising Machine Solver.

    Spins S_i in {-1, 1} (mapped to 0, 1 for SC).
    Energy E = -Sum(J_ij * S_i * S_j) - Sum(h_i * S_i).
    Goal: Find configuration that minimizes E.
    """

    num_spins: int
    J: np.ndarray[Any, Any]  # Coupling matrix (symmetric, zero diagonal)
    h: np.ndarray[Any, Any]  # Bias vector
    temperature: float = 1.0
    anneal_rate: float = 0.99

    def __post_init__(self) -> None:
        """Initialise random spins and their bipolar ``{-1, 1}`` representation."""
        # Initialize spins randomly
        self.spins = np.random.randint(0, 2, self.num_spins).astype(np.int8)
        # Convert 0/1 to -1/1 for physics calc
        self.bipolar_spins = 2 * self.spins - 1

    def step(self) -> float:
        """Perform one parallel Metropolis-Hastings update and return the energy.

        Returns
        -------
        float
            The global Ising energy after applying the accepted spin flips.
        """
        # Calculate local field H_i = Sum(J_ij * S_j) + h_i
        # Using matrix multiplication
        local_field = np.dot(self.J, self.bipolar_spins) + self.h

        # Calculate Energy Difference Delta_E if we flip S_i
        # Delta_E = 2 * S_i * H_i
        # (Physics convention)

        delta_E = 2 * self.bipolar_spins * local_field

        # Probability of flipping: P = min(1, exp(-Delta_E / T))
        # If Delta_E < 0 (flip reduces energy), P=1 (always flip, greedy)
        # If Delta_E > 0 (flip increases energy), P = exp(...)

        # Vectorized probability calculation
        flip_prob = np.exp(-delta_E / self.temperature)
        flip_prob = np.minimum(1.0, flip_prob)

        # Determine flips
        random_draws = np.random.random(self.num_spins)
        should_flip = random_draws < flip_prob

        # Apply flips
        # Flip -1 to 1 and 1 to -1: S_new = -S_old
        self.bipolar_spins[should_flip] *= -1

        # Update 0/1 representation
        self.spins = (self.bipolar_spins + 1) // 2

        # Anneal
        self.temperature *= self.anneal_rate

        return self.get_energy()

    def get_energy(self) -> float:
        """Calculate global energy."""
        # E = -0.5 * S^T * J * S - h^T * S
        # Factor 0.5 because J_ij is counted twice in full matrix sum
        interaction = -0.5 * np.dot(self.bipolar_spins, np.dot(self.J, self.bipolar_spins))
        bias = -np.dot(self.h, self.bipolar_spins)
        return float(interaction + bias)

    def get_config(self) -> np.ndarray[Any, Any]:
        """Return the current spin configuration as a ``0/1`` int8 array."""
        return self.spins

`__post_init__()` ¶

Initialise random spins and their bipolar {-1, 1} representation.

Source code in src/sc_neurocore/solvers/ising.py

Python
def __post_init__(self) -> None:
    """Initialise random spins and their bipolar ``{-1, 1}`` representation."""
    # Initialize spins randomly
    self.spins = np.random.randint(0, 2, self.num_spins).astype(np.int8)
    # Convert 0/1 to -1/1 for physics calc
    self.bipolar_spins = 2 * self.spins - 1

`step()` ¶

Perform one parallel Metropolis-Hastings update and return the energy.

Returns¶

float The global Ising energy after applying the accepted spin flips.

Source code in src/sc_neurocore/solvers/ising.py

Python
def step(self) -> float:
    """Perform one parallel Metropolis-Hastings update and return the energy.

    Returns
    -------
    float
        The global Ising energy after applying the accepted spin flips.
    """
    # Calculate local field H_i = Sum(J_ij * S_j) + h_i
    # Using matrix multiplication
    local_field = np.dot(self.J, self.bipolar_spins) + self.h

    # Calculate Energy Difference Delta_E if we flip S_i
    # Delta_E = 2 * S_i * H_i
    # (Physics convention)

    delta_E = 2 * self.bipolar_spins * local_field

    # Probability of flipping: P = min(1, exp(-Delta_E / T))
    # If Delta_E < 0 (flip reduces energy), P=1 (always flip, greedy)
    # If Delta_E > 0 (flip increases energy), P = exp(...)

    # Vectorized probability calculation
    flip_prob = np.exp(-delta_E / self.temperature)
    flip_prob = np.minimum(1.0, flip_prob)

    # Determine flips
    random_draws = np.random.random(self.num_spins)
    should_flip = random_draws < flip_prob

    # Apply flips
    # Flip -1 to 1 and 1 to -1: S_new = -S_old
    self.bipolar_spins[should_flip] *= -1

    # Update 0/1 representation
    self.spins = (self.bipolar_spins + 1) // 2

    # Anneal
    self.temperature *= self.anneal_rate

    return self.get_energy()

`get_energy()` ¶

Calculate global energy.

Source code in src/sc_neurocore/solvers/ising.py

Python
def get_energy(self) -> float:
    """Calculate global energy."""
    # E = -0.5 * S^T * J * S - h^T * S
    # Factor 0.5 because J_ij is counted twice in full matrix sum
    interaction = -0.5 * np.dot(self.bipolar_spins, np.dot(self.J, self.bipolar_spins))
    bias = -np.dot(self.h, self.bipolar_spins)
    return float(interaction + bias)

`get_config()` ¶

Return the current spin configuration as a 0/1 int8 array.

Source code in src/sc_neurocore/solvers/ising.py

Python
def get_config(self) -> np.ndarray[Any, Any]:
    """Return the current spin configuration as a ``0/1`` int8 array."""
    return self.spins

Exact-current LIF profile¶

ExactCurrentLIFProfile is the versioned semantic contract for the existing ExactLIFSolver exact-flow, hard-reset current-based LIF model. Its canonical JSON and SHA-256 bind the equation, model-source bytes, parameters, normalized units, piecewise-constant input family, analytical crossing solver, inclusive threshold, hard reset, zero refractory interval, explicit shot reset, binary64 behavior, and absence of stochastic state. Unknown fields, schema versions, unit changes, source drift, and digest mismatches fail closed.

ExactCurrentLIFSession preserves voltage and shot-relative time across calls. Each call returns an immutable packet containing the exact producer commit, profile digest, input ticks, initial and final state, exact spike events, and an ordered state trace. Threshold and reset samples share the analytical crossing timestamp, so downstream consumers do not have to infer event ordering from a grid-aligned spike count.

Python

from sc_neurocore.solvers import (
    CurrentDriveTick,
    ExactCurrentLIFProfile,
    ExactCurrentLIFSession,
)

profile = ExactCurrentLIFProfile(tau_ms=10.0)
session = ExactCurrentLIFSession(
    profile,
    producer_commit="0123456789abcdef0123456789abcdef01234567",
    shot_id="mif-shot-17",
)
packet = session.execute(
    [
        CurrentDriveTick(duration_ms=2.0, currents=(10.0, 20.0)),
        CurrentDriveTick(duration_ms=3.0, currents=(30.0,)),
    ]
)
assert packet.profile_digest == profile.digest
checkpoint = session.serialize_state()
validated = type(packet).from_json(
    packet.to_json(),
    profile=profile,
    expected_producer_commit="0123456789abcdef0123456789abcdef01234567",
)
assert validated == packet

The canonical default profile and a four-tick complete-state receipt are shipped as exact_current_lif_profile_v1.json and exact_current_lif_multitick_v1.json under src/sc_neurocore/neurons/reference_trace_data/. The receipt binds its profile digest and the exact implementation commit and includes three off-grid events.

The profile is a precise software/reference contract. It does not by itself claim fixed-point equivalence, generated RTL parity, synthesis timing, PPA, board/HIL evidence, or biological fidelity. Those remain separate gates.

`sc_neurocore.solvers.exact_lif_profile` ¶

Digest-bound, stateful execution for the exact-current SC LIF profile.

The profile binds the existing :class:ExactLIFSolver implementation rather than introducing another neuron model. It makes the solver, units, event ordering, reset boundary and numerical behaviour explicit for consumers.