pyqrack-cpu 1.82.0__py3-none-macosx_15_0_arm64.whl

pyqrack/qrack_neuron.py

@@ -0,0 +1,381 @@
+# (C) Daniel Strano and the Qrack contributors 2017-2025. All rights reserved.
+#
+# Use of this source code is governed by an MIT-style license that can be
+# found in the LICENSE file or at https://opensource.org/licenses/MIT.
+
+import ctypes
+import sys
+
+from .qrack_system import Qrack
+from .neuron_activation_fn import NeuronActivationFn
+
+
+class QrackNeuron:
+    """Class that exposes the QNeuron class of Qrack
+
+    This model of a "quantum neuron" is based on the concept of a "uniformly controlled"
+    rotation of a single output qubit around the Pauli Y axis, and has been developed by
+    others. In our case, the primary relevant gate could also be called a
+    single-qubit-target multiplexer.
+
+    (See https://arxiv.org/abs/quant-ph/0407010 for an introduction to "uniformly controlled
+    gates.)
+
+    QrackNeuron is meant to be interchangeable with a single classical neuron, as in
+    conventional neural net software. It differs from classical neurons in conventional
+    neural nets, in that the "synaptic cleft" is modelled as a single qubit. Hence, this
+    neuron can train and predict in superposition.
+
+    Attributes:
+        nid(int): Qrack ID of this neuron
+        simulator(QrackSimulator): Simulator instance for all synaptic clefts of the neuron
+        controls(list(int)): Indices of all "control" qubits, for neuron input
+        target(int): Index of "target" qubit, for neuron output
+        activation_fn(NeuronActivationFn): Activation function choice
+        alpha(float): Activation function parameter, if required
+        angles(list[ctypes.c_float]): (or c_double) Memory for neuron prediction angles
+    """
+
+    def _get_error(self):
+        return Qrack.qrack_lib.get_error(self.simulator.sid)
+
+    def _throw_if_error(self):
+        if self._get_error() != 0:
+            raise RuntimeError("QrackNeuron C++ library raised exception.")
+
+    def __init__(
+        self,
+        simulator,
+        controls,
+        target,
+        activation_fn=NeuronActivationFn.Sigmoid,
+        alpha=1.0,
+        _init=True,
+    ):
+        self.simulator = simulator
+        self.controls = controls
+        self.target = target
+        self.activation_fn = activation_fn
+        self.alpha = alpha
+        self.angles = QrackNeuron._real1_byref([0.0] * (1 << len(controls)))
+
+        if not _init:
+            return
+
+        self.nid = Qrack.qrack_lib.init_qneuron(
+            simulator.sid,
+            len(controls),
+            QrackNeuron._ulonglong_byref(controls),
+            target,
+        )
+
+        self._throw_if_error()
+
+    def __del__(self):
+        if self.nid is not None:
+            Qrack.qrack_lib.destroy_qneuron(self.nid)
+            self.nid = None
+
+    def clone(self):
+        """Clones this neuron.
+
+        Create a new, independent neuron instance with identical angles,
+        inputs, output, and tolerance, for the same QrackSimulator.
+
+        Raises:
+            RuntimeError: QrackNeuron C++ library raised an exception.
+        """
+        result = QrackNeuron(
+            self.simulator,
+            self.controls,
+            self.target,
+        )
+        result.nid = Qrack.qrack_lib.clone_qneuron(self.simulator.sid)
+        result.angles = self.angles[:]
+        self._throw_if_error()
+        return result
+
+    @staticmethod
+    def _ulonglong_byref(a):
+        return (ctypes.c_ulonglong * len(a))(*a)
+
+    @staticmethod
+    def _real1_byref(a):
+        # This needs to be c_double, if PyQrack is built with fp64.
+        if Qrack.fppow < 6:
+            return (ctypes.c_float * len(a))(*a)
+        return (ctypes.c_double * len(a))(*a)
+
+    def set_simulator(self, s, controls=None, target=None):
+        """Set the neuron simulator
+
+        Set the simulator used by this neuron
+
+        Args:
+            s(QrackSimulator): The simulator to use
+            controls(list[int]): The control qubit IDs to use
+            target(int): The output qubit ID to use
+
+        Raises:
+            RuntimeError: QrackSimulator raised an exception.
+        """
+        if controls is None:
+            controls = self.controls
+        if target is None:
+            target = self.target
+        Qrack.qrack_lib.set_qneuron_sim(
+            self.nid,
+            s.sid,
+            len(controls),
+            QrackNeuron._ulonglong_byref(controls),
+            target,
+        )
+        self._throw_if_error()
+        self.simulator = s
+        self.controls = controls
+        self.target = target
+
+    def set_qubit_ids(self, controls, target=None):
+        """Set the neuron qubit identifiers
+
+        Set the control and target qubits within the simulator
+
+        Args:
+            controls(list[int]): The control qubit IDs to use
+            target(int): The output qubit ID to use
+
+        Raises:
+            RuntimeError: QrackSimulator raised an exception.
+        """
+        if target is None:
+            target = self.target
+        self.set_simulator(self.simulator, controls, target)
+
+    def set_angles(self, a):
+        """Directly sets the neuron parameters.
+
+        Set all synaptic parameters of the neuron directly, by a list
+        enumerated over the integer permutations of input qubits.
+
+        Args:
+            a(list(double)): List of input permutation angles
+
+        Raises:
+            ValueError: Angles 'a' in QrackNeuron.set_angles() must contain at least (2 ** len(self.controls)) elements.
+            RuntimeError: QrackSimulator raised an exception.
+        """
+        if len(a) < (1 << len(self.controls)):
+            raise ValueError(
+                "Angles 'a' in QrackNeuron.set_angles() must contain at least (2 ** len(self.controls)) elements."
+            )
+        self.angles = QrackNeuron._real1_byref(a)
+
+    def get_angles(self):
+        """Directly gets the neuron parameters.
+
+        Get all synaptic parameters of the neuron directly, as a list
+        enumerated over the integer permutations of input qubits.
+
+        Raises:
+            RuntimeError: QrackNeuron C++ library raised an exception.
+        """
+        return list(self.angles)
+
+    def set_alpha(self, a):
+        """Set the neuron 'alpha' parameter.
+
+        To enable nonlinear activation, `QrackNeuron` has an 'alpha'
+        parameter that is applied as a power to its angles, before
+        learning and prediction. This makes the activation function
+        sharper (or less sharp).
+        """
+        self.alpha = a
+
+    def set_activation_fn(self, f):
+        """Sets the activation function of this QrackNeuron
+
+        Nonlinear activation functions can be important to neural net
+        applications, like DNN. The available activation functions are
+        enumerated in `NeuronActivationFn`.
+        """
+        self.activation_fn = f
+
+    def predict(self, e=True, r=True):
+        """Predict based on training
+
+        "Predict" the anticipated output, based on input and training.
+        By default, "predict()" will initialize the output qubit as by
+        resetting to |0> and then acting a Hadamard gate. From that
+        state, the method amends the output qubit upon the basis of
+        the state of its input qubits, applying a rotation around
+        Pauli Y axis according to the angle learned for the input.
+
+        Args:
+            e(bool): If False, predict the opposite
+            r(bool): If True, start by resetting the output to 50/50
+
+        Raises:
+            RuntimeError: QrackNeuron C++ library raised an exception.
+        """
+        result = Qrack.qrack_lib.qneuron_predict(self.nid, self.angles, e, r, self.activation_fn, self.alpha)
+        self._throw_if_error()
+        return result
+
+    def unpredict(self, e=True):
+        """Uncompute a prediction
+
+        Uncompute a 'prediction' of the anticipated output, based on
+        input and training.
+
+        Args:
+            e(bool): If False, unpredict the opposite
+
+        Raises:
+            RuntimeError: QrackNeuron C++ library raised an exception.
+        """
+        result = Qrack.qrack_lib.qneuron_unpredict(self.nid, self.angles, e, self.activation_fn, self.alpha)
+        self._throw_if_error()
+        return result
+
+    def learn_cycle(self, e=True):
+        """Run a learning cycle
+
+        A learning cycle consists of predicting a result, saving the
+        classical outcome, and uncomputing the prediction.
+
+        Args:
+            e(bool): If False, predict the opposite
+
+        Raises:
+            RuntimeError: QrackNeuron C++ library raised an exception.
+        """
+        Qrack.qrack_lib.qneuron_learn_cycle(self.nid, self.angles, e, self.activation_fn, self.alpha)
+        self._throw_if_error()
+
+    def learn(self, eta, e=True, r=True):
+        """Learn from current qubit state
+
+        "Learn" to associate current inputs with output. Based on
+        input qubit states and volatility 'eta,' the input state
+        synaptic parameter is updated to prefer the "e" ("expected")
+        output.
+
+        Args:
+            eta(double): Training volatility, 0 to 1
+            e(bool): If False, predict the opposite
+            r(bool): If True, start by resetting the output to 50/50
+
+        Raises:
+            RuntimeError: QrackNeuron C++ library raised an exception.
+        """
+        Qrack.qrack_lib.qneuron_learn(self.nid, self.angles, eta, e, r, self.activation_fn, self.alpha)
+        self._throw_if_error()
+
+    def learn_permutation(self, eta, e=True, r=True):
+        """Learn from current classical state
+
+        Learn to associate current inputs with output, under the
+        assumption that the inputs and outputs are "classical."
+        Based on input qubit states and volatility 'eta,' the input
+        state angle is updated to prefer the "e" ("expected") output.
+
+        Args:
+            eta(double): Training volatility, 0 to 1
+            e(bool): If False, predict the opposite
+            r(bool): If True, start by resetting the output to 50/50
+
+        Raises:
+            RuntimeError: QrackNeuron C++ library raised an exception.
+        """
+        Qrack.qrack_lib.qneuron_learn_permutation(self.nid, self.angles, eta, e, r, self.activation_fn, self.alpha)
+        self._throw_if_error()
+
+    @staticmethod
+    def quantile_bounds(vec, bits):
+        """Calculate vector quantile bounds
+
+        This is a static helper method to calculate the quantile
+        bounds of 2 ** bits worth of quantiles.
+
+        Args:
+            vec: numerical vector
+            bits: log2() of quantile count
+
+        Returns:
+            Quantile (n + 1) bounds for n-quantile division, including
+            minimum and maximum values
+        """
+
+        bins = 1 << bits
+        n = len(vec)
+        vec_sorted = sorted(vec)
+
+        return (
+            [vec_sorted[0]]
+            + [vec_sorted[(k * n) // bins] for k in range(1, bins)]
+            + [vec_sorted[-1]]
+        )
+
+    @staticmethod
+    def discretize(vec, bounds):
+        """Discretize vector by quantile bounds
+
+        This is a static helper method to discretize a numerical
+        vector according to quantile bounds calculated by the
+        quantile_bounds(vec, bits) static method.
+
+        Args:
+            vec: numerical vector
+            bounds: (n + 1) n-quantile bounds including extrema
+
+        Returns:
+            Discretized bit-row vector, least-significant first
+        """
+
+        bounds = bounds[1:]
+        bounds_len = len(bounds)
+        bits = bounds_len.bit_length() - 1
+        n = len(vec)
+        vec_discrete = [[False] * n for _ in range(bits)]
+        for i, v in enumerate(vec):
+            p = 0
+            while (p < bounds_len) and (v > bounds[p]):
+                p += 1
+            for b in range(bits):
+                vec_discrete[b][i] = bool((p >> b) & 1)
+
+        return vec_discrete
+
+    @staticmethod
+    def flatten_and_transpose(arr):
+        """Flatten and transpose feature matrix
+
+        This is a static helper method to convert a multi-feature
+        bit-row matrix to an observation-row matrix with flat
+        feature columns.
+
+        Args:
+            arr: bit-row matrix
+
+        Returns:
+            Observation-row matrix with flat feature columns
+        """
+        return list(zip(*[item for sublist in arr for item in sublist]))
+
+    @staticmethod
+    def bin_endpoints_average(bounds):
+        """Bin endpoints average
+
+        This is a static helper method that accepts the output
+        bins from quantile_bounds() and returns the average points
+        between the bin endpoints. (This is NOT always necessarily
+        the best heuristic for how to convert binned results back
+        to numerical results, but it is often a reasonable way.)
+
+        Args:
+            bounds: (n + 1) n-quantile bounds including extrema
+
+        Returns:
+            List of average points between the bin endpoints
+        """
+        return [((bounds[i] + bounds[i + 1]) / 2) for i in range(len(bounds) - 1)]

pyqrack/qrack_neuron_torch_layer.py

@@ -0,0 +1,257 @@
+# (C) Daniel Strano and the Qrack contributors 2017-2026. All rights reserved.
+#
+# Initial draft by Elara (OpenAI custom GPT)
+# Refined and architecturally clarified by Dan Strano
+#
+# Use of this source code is governed by an MIT-style license that can be
+# found in the LICENSE file or at https://opensource.org/licenses/MIT.
+
+import ctypes
+import itertools
+import math
+import random
+import sys
+
+_IS_TORCH_AVAILABLE = True
+try:
+    import torch
+    import torch.nn as nn
+    from torch.autograd import Function
+except ImportError:
+    _IS_TORCH_AVAILABLE = False
+
+from .pauli import Pauli
+from .qrack_neuron import QrackNeuron
+from .qrack_simulator import QrackSimulator
+from .qrack_system import Qrack
+from .neuron_activation_fn import NeuronActivationFn
+
+
+# Parameter-shift rule
+param_shift_eps = math.pi / 2
+# Neuron angle initialization
+init_phi = math.asin(0.5)
+# Systemic floating-point type
+fp_type = ctypes.c_float if Qrack.fppow <= 5 else ctypes.c_double
+
+
+class QrackNeuronTorchFunction(Function if _IS_TORCH_AVAILABLE else object):
+    """Static forward/backward/apply functions for QrackNeuronTorch"""
+
+    @staticmethod
+    def forward(ctx, x, neuron):
+        ctx.neuron = neuron
+        ctx.simulator = neuron.simulator
+        ctx.save_for_backward(x)
+
+        # Baseline probability BEFORE applying this neuron's unitary
+        pre_prob = neuron.simulator.prob(neuron.target)
+
+        angles = x.detach().cpu().numpy() if x.requires_grad else x.numpy()
+        neuron.angles = angles.ctypes.data_as(ctypes.POINTER(fp_type))
+        neuron.predict(True, False)
+
+        # Probability AFTER applying this neuron's unitary
+        post_prob = neuron.simulator.prob(neuron.target)
+        ctx.post_prob = post_prob
+
+        delta = math.asin(post_prob) - math.asin(pre_prob)
+        ctx.delta = delta
+
+        # Return shape: (1,)
+        return x.new_tensor([delta])
+
+    @staticmethod
+    def backward(ctx, grad_output):
+        (x,) = ctx.saved_tensors
+        neuron = ctx.neuron
+        neuron.set_simulator(ctx.simulator)
+        post_prob = ctx.post_prob
+
+        angles = x.detach().cpu().numpy() if x.requires_grad else x.numpy()
+
+        # Restore simulator to state BEFORE this neuron's unitary
+        neuron.angles = angles.ctypes.data_as(ctypes.POINTER(fp_type))
+        neuron.unpredict()
+        pre_sim = neuron.simulator
+
+        grad_x = torch.zeros_like(x)
+
+        for i in range(x.shape[0]):
+            angle = angles[i]
+
+            # θ + π/2
+            angles[i] = angle + param_shift_eps
+            neuron.set_angles(angles)
+            neuron.simulator = pre_sim.clone()
+            neuron.predict(True, False)
+            p_plus = neuron.simulator.prob(neuron.target)
+
+            # θ − π/2
+            angles[i] = angle - param_shift_eps
+            neuron.set_angles(angles)
+            neuron.simulator = pre_sim.clone()
+            neuron.predict(True, False)
+            p_minus = neuron.simulator.prob(neuron.target)
+
+            # Parameter-shift gradient
+            grad_x[i] = 0.5 * (p_plus - p_minus)
+
+            angles[i] = angle
+
+        # Restore simulator
+        neuron.set_simulator(pre_sim)
+
+        # Apply chain rule and upstream gradient
+        grad_x *= grad_output[0] / math.sqrt(max(1.0 - post_prob * post_prob, 1e-6))
+
+        return grad_x, None
+
+
+class QrackNeuronTorch(nn.Module if _IS_TORCH_AVAILABLE else object):
+    """Torch wrapper for QrackNeuron
+
+    Attributes:
+        neuron(QrackNeuron): QrackNeuron backing this torch wrapper
+    """
+
+    def __init__(self, neuron, x):
+        super().__init__()
+        self.neuron = neuron
+        self.weights = nn.Parameter(x)
+
+    def forward(self):
+        return QrackNeuronTorchFunction.apply(self.weights, self.neuron)
+
+
+class QrackNeuronTorchLayer(nn.Module if _IS_TORCH_AVAILABLE else object):
+    """Torch layer wrapper for QrackNeuron (with maximally expressive set of neurons between inputs and outputs)
+
+    Attributes:
+        simulator (QrackSimulator): Prototype simulator that batching copies to use with QrackNeuron instances. (You may customize or overwrite the initialization or reference, before calling forward(x).)
+        simulators (list[QrackSimulator]): In-flight copies of prototype simulator corresponding to batch count
+        input_indices (list[int], read-only): simulator qubit indices used as QrackNeuron inputs
+        output_indices (list[int], read-only): simulator qubit indices used as QrackNeuron outputs
+        hidden_indices (list[int], read-only): simulator qubit indices used as QrackNeuron hidden inputs (in maximal superposition)
+        neurons (ModuleList[QrackNeuronTorch]): QrackNeuronTorch wrappers (for PyQrack QrackNeurons) in this layer, corresponding to weights
+        weights (ParameterList): List of tensors corresponding one-to-one with weights of list of neurons
+        apply_fn (Callable[Tensor, QrackNeuronTorch]): Corresponds to QrackNeuronTorchFunction.apply(x, neuron_wrapper) (or override with a custom implementation)
+        post_init_fn (Callable[QrackSimulator]): Function that is applied after forward(x) state initialization, before inference. (As the function depends on nothing but the simulator, it's differentiable.)
+    """
+
+    def __init__(
+        self,
+        input_qubits,
+        output_qubits,
+        hidden_qubits=None,
+        lowest_combo_count=0,
+        highest_combo_count=2,
+        activation=int(NeuronActivationFn.Generalized_Logistic),
+        parameters=None,
+        post_init_fn=lambda simulator: None,
+        **kwargs
+    ):
+        """
+        Initialize a QrackNeuron layer for PyTorch with a power set of neurons connecting inputs to outputs.
+        The inputs and outputs must take the form of discrete, binary features (loaded manually into the backing QrackSimulator)
+
+        Args:
+            sim (QrackSimulator): Simulator into which predictor features are loaded
+            input_qubits (int): Count of inputs (1 per qubit)
+            output_qubits (int): Count of outputs (1 per qubit)
+            hidden_qubits (int): (Optional) Count of "hidden" inputs (1 per qubit, always initialized to |+>, suggested to be same a highest_combo_count)
+            lowest_combo_count (int): (Optional) Lowest combination count of input qubits iterated (0 is bias)
+            highest_combo_count (int): (Optional) Highest combination count of input qubits iterated
+            activation (int): (Optional) Integer corresponding to choice of activation function from NeuronActivationFn
+            parameters (list[float]): (Optional) Flat list of initial neuron parameters, corresponding to little-endian basis states of input + hidden qubits, repeated for ascending combo count, repeated for each output index
+            post_init_fn (Callable[QrackSimulator]): (Optional) Function that is applied after forward(x) state initialization, before inference. (As the function depends on nothing but the simulator, it's differentiable.)
+        """
+        super(QrackNeuronTorchLayer, self).__init__()
+        if hidden_qubits is None:
+            hidden_qubits = highest_combo_count
+        self.simulator = QrackSimulator(input_qubits + hidden_qubits + output_qubits, **kwargs)
+        self.simulators = []
+        self.input_indices = list(range(input_qubits))
+        self.hidden_indices = list(range(input_qubits, input_qubits + hidden_qubits))
+        self.output_indices = list(
+            range(input_qubits + hidden_qubits, input_qubits + hidden_qubits + output_qubits)
+        )
+        self.activation = NeuronActivationFn(activation)
+        self.dtype = torch.float if Qrack.fppow <= 5 else torch.double
+        self.apply_fn = QrackNeuronTorchFunction.apply
+        self.post_init_fn = post_init_fn
+
+        # Create neurons from all input combinations, projecting to coherent output qubits
+        neurons = []
+        param_count = 0
+        for output_id in self.output_indices:
+            for k in range(lowest_combo_count, highest_combo_count + 1):
+                for input_subset in itertools.combinations(self.input_indices, k):
+                    p_count = 1 << len(input_subset)
+                    angles = (
+                        (
+                            torch.tensor(
+                                parameters[param_count : (param_count + p_count)], dtype=self.dtype
+                            )
+                            if parameters
+                            else torch.zeros(p_count, dtype=self.dtype)
+                        )
+                    )
+                    neurons.append(
+                        QrackNeuronTorch(
+                            QrackNeuron(self.simulator, input_subset, output_id, activation), angles
+                        )
+                    )
+                    param_count += p_count
+        self.neurons = nn.ModuleList(neurons)
+
+        # Prepare the state before feed-forward:
+
+        # Prepare hidden predictors
+        for hidden_id in self.hidden_indices:
+            self.simulator.h(hidden_id)
+        # Prepare a maximally uncertain output state.
+        for output_id in self.output_indices:
+            self.simulator.h(output_id)
+
+    def forward(self, x):
+        B = x.shape[0]
+        x = x.view(B, -1)
+
+        self.simulators.clear()
+
+        # Group neurons by output target once
+        by_out = {out: [] for out in self.output_indices}
+        for neuron_wrapper in self.neurons:
+            by_out[neuron_wrapper.neuron.target].append(neuron_wrapper)
+
+        batch_rows = []
+        for b in range(B):
+            simulator = self.simulator.clone()
+            self.simulators.append(simulator)
+
+            # Apply feed-forward
+            for q, input_id in enumerate(self.input_indices):
+                simulator.r(Pauli.PauliY, math.pi * x[b, q].item(), input_id)
+
+            # Differentiable post-initialization:
+            self.post_init_fn(simulator)
+
+            row = []
+            for out in self.output_indices:
+                phi = torch.tensor(init_phi, device=x.device, dtype=x.dtype)
+
+                for neuron_wrapper in by_out[out]:
+                    neuron_wrapper.neuron.set_simulator(simulator)
+                    phi += self.apply_fn(
+                        neuron_wrapper.weights,
+                        neuron_wrapper.neuron
+                    ).squeeze()
+
+                # Convert angle back to probability
+                p = torch.clamp(torch.sin(phi), min=0.0)
+                row.append(p)
+
+            batch_rows.append(torch.stack(row))
+
+        return torch.stack(batch_rows)