pyqrack-complex128 1.65.2__py3-none-macosx_14_0_arm64.whl → 1.81.0__py3-none-macosx_14_0_arm64.whl

pyqrack/qrack_neuron.py

@@ -31,7 +31,9 @@ class QrackNeuron:
         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
-        tolerance(double): Rounding tolerance
+        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):
@@ -48,7 +50,6 @@ class QrackNeuron:
         target,
         activation_fn=NeuronActivationFn.Sigmoid,
         alpha=1.0,
-        tolerance=sys.float_info.epsilon,
         _init=True,
     ):
         self.simulator = simulator
@@ -56,7 +57,7 @@ class QrackNeuron:
         self.target = target
         self.activation_fn = activation_fn
         self.alpha = alpha
-        self.tolerance = tolerance
+        self.angles = QrackNeuron._real1_byref([0.0] * (1 << len(controls)))
 
         if not _init:
             return
@@ -64,11 +65,8 @@ class QrackNeuron:
         self.nid = Qrack.qrack_lib.init_qneuron(
             simulator.sid,
             len(controls),
-            self._ulonglong_byref(controls),
+            QrackNeuron._ulonglong_byref(controls),
             target,
-            activation_fn,
-            alpha,
-            tolerance,
         )
 
         self._throw_if_error()
@@ -91,23 +89,44 @@ class QrackNeuron:
             self.simulator,
             self.controls,
             self.target,
-            self.activation_fn,
-            self.alpha,
-            self.tolerance,
         )
-        self.nid = Qrack.qrack_lib.clone_qneuron(self.simulator.sid)
+        result.nid = Qrack.qrack_lib.clone_qneuron(self.simulator.sid)
+        result.angles = self.angles[:]
         self._throw_if_error()
         return result
 
-    def _ulonglong_byref(self, a):
+    @staticmethod
+    def _ulonglong_byref(a):
         return (ctypes.c_ulonglong * len(a))(*a)
 
-    def _real1_byref(self, 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):
+        """Set the neuron simulator
+
+        Set the simulator used by this neuron
+
+        Args:
+            s(QrackSimulator): The simulator to use
+
+        Raises:
+            RuntimeError: QrackSimulator raised an exception.
+        """
+        Qrack.qrack_lib.set_qneuron_sim(
+            self.nid,
+            s.sid,
+            len(self.controls),
+            QrackNeuron._ulonglong_byref(self.controls),
+            self.target,
+        )
+        self._throw_if_error()
+        self.simulator = s
+
     def set_angles(self, a):
         """Directly sets the neuron parameters.
 
@@ -125,8 +144,7 @@ class QrackNeuron:
             raise ValueError(
                 "Angles 'a' in QrackNeuron.set_angles() must contain at least (2 ** len(self.controls)) elements."
             )
-        Qrack.qrack_lib.set_qneuron_angles(self.nid, self._real1_byref(a))
-        self._throw_if_error()
+        self.angles = QrackNeuron._real1_byref(a)
 
     def get_angles(self):
         """Directly gets the neuron parameters.
@@ -137,10 +155,7 @@ class QrackNeuron:
         Raises:
             RuntimeError: QrackNeuron C++ library raised an exception.
         """
-        ket = self._real1_byref([0.0] * (1 << len(self.controls)))
-        Qrack.qrack_lib.get_qneuron_angles(self.nid, ket)
-        self._throw_if_error()
-        return list(ket)
+        return list(self.angles)
 
     def set_alpha(self, a):
         """Set the neuron 'alpha' parameter.
@@ -149,13 +164,8 @@ class QrackNeuron:
         parameter that is applied as a power to its angles, before
         learning and prediction. This makes the activation function
         sharper (or less sharp).
-
-        Raises:
-            RuntimeError: QrackNeuron C++ library raised an exception.
         """
         self.alpha = a
-        Qrack.qrack_lib.set_qneuron_alpha(self.nid, a)
-        self._throw_if_error()
 
     def set_activation_fn(self, f):
         """Sets the activation function of this QrackNeuron
@@ -163,13 +173,8 @@ class QrackNeuron:
         Nonlinear activation functions can be important to neural net
         applications, like DNN. The available activation functions are
         enumerated in `NeuronActivationFn`.
-
-        Raises:
-            RuntimeError: QrackNeuron C++ library raised an exception.
         """
         self.activation_fn = f
-        Qrack.qrack_lib.set_qneuron_activation_fn(self.nid, f)
-        self._throw_if_error()
 
     def predict(self, e=True, r=True):
         """Predict based on training
@@ -188,7 +193,7 @@ class QrackNeuron:
         Raises:
             RuntimeError: QrackNeuron C++ library raised an exception.
         """
-        result = Qrack.qrack_lib.qneuron_predict(self.nid, e, r)
+        result = Qrack.qrack_lib.qneuron_predict(self.nid, self.angles, e, r, self.activation_fn, self.alpha)
         self._throw_if_error()
         return result
 
@@ -204,7 +209,7 @@ class QrackNeuron:
         Raises:
             RuntimeError: QrackNeuron C++ library raised an exception.
         """
-        result = Qrack.qrack_lib.qneuron_unpredict(self.nid, e)
+        result = Qrack.qrack_lib.qneuron_unpredict(self.nid, self.angles, e, self.activation_fn, self.alpha)
         self._throw_if_error()
         return result
 
@@ -220,7 +225,7 @@ class QrackNeuron:
         Raises:
             RuntimeError: QrackNeuron C++ library raised an exception.
         """
-        Qrack.qrack_lib.qneuron_learn_cycle(self.nid, e)
+        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):
@@ -239,7 +244,7 @@ class QrackNeuron:
         Raises:
             RuntimeError: QrackNeuron C++ library raised an exception.
         """
-        Qrack.qrack_lib.qneuron_learn(self.nid, eta, e, r)
+        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):
@@ -258,5 +263,95 @@ class QrackNeuron:
         Raises:
             RuntimeError: QrackNeuron C++ library raised an exception.
         """
-        Qrack.qrack_lib.qneuron_learn_permutation(self.nid, eta, e, r)
+        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

@@ -1,4 +1,4 @@
-# (C) Daniel Strano and the Qrack contributors 2017-2025. All rights reserved.
+# (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
@@ -6,6 +6,12 @@
 # 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
@@ -14,82 +20,136 @@ try:
 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
 
-from itertools import chain, combinations
 
+# 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
 
-# From https://stackoverflow.com/questions/1482308/how-to-get-all-subsets-of-a-set-powerset#answer-1482316
-def powerset(iterable):
-    "powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3,) (1,2,3)"
-    s = list(iterable)
-    return chain.from_iterable(combinations(s, r) for r in range(len(s) + 1))
 
+class QrackNeuronTorchFunction(Function if _IS_TORCH_AVAILABLE else object):
+    """Static forward/backward/apply functions for QrackNeuronTorch"""
 
-class QrackTorchNeuron(nn.Module if _IS_TORCH_AVAILABLE else object):
-    """Torch wrapper for QrackNeuron
+    @staticmethod
+    def forward(ctx, x, neuron):
+        ctx.neuron = neuron
+        ctx.simulator = neuron.simulator
+        ctx.save_for_backward(x)
 
-    Attributes:
-        neuron(QrackNeuron): QrackNeuron backing this torch wrapper
-    """
+        # Baseline probability BEFORE applying this neuron's unitary
+        pre_prob = neuron.simulator.prob(neuron.target)
 
-    def __init__(self, neuron: QrackNeuron):
-        super().__init__()
-        self.neuron = neuron
-
-    def forward(self, x):
-        neuron = self.neuron
+        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)
 
-        return neuron.simulator.prob(neuron.target)
-
-
-class QrackNeuronFunction(Function if _IS_TORCH_AVAILABLE else object):
-    """Static forward/backward/apply functions for QrackTorchNeuron"""
-
-    @staticmethod
-    def forward(ctx, neuron):
-        # Save for backward
-        ctx.neuron = neuron
+        # Probability AFTER applying this neuron's unitary
+        post_prob = neuron.simulator.prob(neuron.target)
+        ctx.post_prob = post_prob
 
-        init_prob = neuron.simulator.prob(neuron.target)
-        neuron.predict(True, False)
-        final_prob = neuron.simulator.prob(neuron.target)
-        ctx.delta = final_prob - init_prob
+        delta = math.asin(post_prob) - math.asin(pre_prob)
+        ctx.delta = delta
 
-        return (
-            torch.tensor([ctx.delta], dtype=torch.float32)
-            if _IS_TORCH_AVAILABLE
-            else ctx.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()
 
-        pre_unpredict = neuron.simulator.prob(neuron.output_id)
+        # Restore simulator to state BEFORE this neuron's unitary
+        neuron.angles = angles.ctypes.data_as(ctypes.POINTER(fp_type))
         neuron.unpredict()
-        post_unpredict = neuron.simulator.prob(neuron.output_id)
-        reverse_delta = pre_unpredict - post_unpredict
+        pre_sim = neuron.simulator
 
-        grad = reverse_delta - ctx.delta
+        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
 
-        return (
-            torch.tensor([grad], dtype=torch.float32) if _IS_TORCH_AVAILABLE else grad
-        )
+
+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 power set of neurons between inputs and outputs)"""
+    """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,
-        simulator,
-        input_indices,
-        output_indices,
+        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.
@@ -97,74 +157,101 @@ class QrackNeuronTorchLayer(nn.Module if _IS_TORCH_AVAILABLE else object):
 
         Args:
             sim (QrackSimulator): Simulator into which predictor features are loaded
-            input_indices (list[int]): List of input bits
-            output_indices (list[int]): List of output bits
-            activation (int): 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 power set of input indices, repeated for each output index (with empty set being constant bias)
+            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__()
-        self.simulator = simulator
-        self.input_indices = input_indices
-        self.output_indices = output_indices
-        self.activation = NeuronActivationFn(activation)
-        self.fn = (
-            QrackNeuronFunction.apply
-            if _IS_TORCH_AVAILABLE
-            else lambda x: QrackNeuronFunction.forward(object(), x)
-        )
-
-        # Create neurons from all powerset input combinations, projecting to coherent output qubits
-        self.neurons = nn.ModuleList(
-            [
-                QrackTorchNeuron(
-                    QrackNeuron(simulator, list(input_subset), output_id, activation)
-                )
-                for input_subset in powerset(input_indices)
-                for output_id in output_indices
-            ]
+        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
 
-        # Set Qrack's internal parameters:
+        # Create neurons from all input combinations, projecting to coherent output qubits
+        neurons = []
         param_count = 0
-        for neuron_wrapper in self.neurons:
-            neuron = neuron_wrapper.neuron
-            p_count = 1 << len(neuron.controls)
-            neuron.set_angles(
-                parameters[param_count : (param_count + p_count + 1)]
-                if parameters
-                else ([0.0] * p_count)
-            )
-            param_count += p_count
-
-        self.weights = nn.ParameterList()
-        for pid in range(param_count):
-            self.weights.append(
-                nn.Parameter(torch.tensor(parameters[pid] if parameters else 0.0))
-            )
-
-    def forward(self, _):
-        # Assume quantum outputs should overwrite the simulator state
         for output_id in self.output_indices:
-            if self.simulator.m(output_id):
-                self.simulator.x(output_id)
+            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)
 
-        # Set Qrack's internal parameters:
-        param_count = 0
-        for neuron_wrapper in self.neurons:
-            neuron = neuron_wrapper.neuron
-            p_count = 1 << len(neuron.controls)
-            angles = [
-                w.item() for w in self.weights[param_count : (param_count + p_count)]
-            ]
-            neuron.set_angles(angles)
-            param_count += p_count
+    def forward(self, x):
+        B = x.shape[0]
+        x = x.view(B, -1)
 
-        # Assume quantum inputs already loaded into simulator state
+        self.simulators.clear()
+
+        # Group neurons by output target once
+        by_out = {out: [] for out in self.output_indices}
         for neuron_wrapper in self.neurons:
-            self.fn(neuron_wrapper.neuron)
+            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)
 
-        # These are classical views over quantum state; simulator still maintains full coherence
-        outputs = [self.simulator.prob(output_id) for output_id in self.output_indices]
+            batch_rows.append(torch.stack(row))
 
-        return torch.tensor(outputs, dtype=torch.float32)
+        return torch.stack(batch_rows)