pyqrack 1.70.0__py3-none-macosx_13_0_x86_64.whl

pyqrack/qrack_neuron.py

@@ -0,0 +1,262 @@
+# (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
+        tolerance(double): Rounding tolerance
+    """
+
+    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,
+        tolerance=sys.float_info.epsilon,
+        _init=True,
+    ):
+        self.simulator = simulator
+        self.controls = controls
+        self.target = target
+        self.activation_fn = activation_fn
+        self.alpha = alpha
+        self.tolerance = tolerance
+
+        if not _init:
+            return
+
+        self.nid = Qrack.qrack_lib.init_qneuron(
+            simulator.sid,
+            len(controls),
+            self._ulonglong_byref(controls),
+            target,
+            activation_fn,
+            alpha,
+            tolerance,
+        )
+
+        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,
+            self.activation_fn,
+            self.alpha,
+            self.tolerance,
+        )
+        self.nid = Qrack.qrack_lib.clone_qneuron(self.simulator.sid)
+        self._throw_if_error()
+        return result
+
+    def _ulonglong_byref(self, a):
+        return (ctypes.c_ulonglong * len(a))(*a)
+
+    def _real1_byref(self, 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_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."
+            )
+        Qrack.qrack_lib.set_qneuron_angles(self.nid, self._real1_byref(a))
+        self._throw_if_error()
+
+    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.
+        """
+        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)
+
+    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).
+
+        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
+
+        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
+
+        "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, e, r)
+        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, e)
+        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, e)
+        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, eta, e, r)
+        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, eta, e, r)
+        self._throw_if_error()

pyqrack/qrack_neuron_torch_layer.py

@@ -0,0 +1,170 @@
+# (C) Daniel Strano and the Qrack contributors 2017-2025. 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.
+
+_IS_TORCH_AVAILABLE = True
+try:
+    import torch
+    import torch.nn as nn
+    from torch.autograd import Function
+except ImportError:
+    _IS_TORCH_AVAILABLE = False
+
+from .qrack_neuron import QrackNeuron
+from .neuron_activation_fn import NeuronActivationFn
+
+from itertools import chain, combinations
+
+
+# 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 QrackTorchNeuron(nn.Module if _IS_TORCH_AVAILABLE else object):
+    """Torch wrapper for QrackNeuron
+
+    Attributes:
+        neuron(QrackNeuron): QrackNeuron backing this torch wrapper
+    """
+
+    def __init__(self, neuron: QrackNeuron):
+        super().__init__()
+        self.neuron = neuron
+
+    def forward(self, x):
+        neuron = self.neuron
+        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
+
+        init_prob = neuron.simulator.prob(neuron.target)
+        neuron.predict(True, False)
+        final_prob = neuron.simulator.prob(neuron.target)
+        ctx.delta = final_prob - init_prob
+
+        return (
+            torch.tensor([ctx.delta], dtype=torch.float32)
+            if _IS_TORCH_AVAILABLE
+            else ctx.delta
+        )
+
+    @staticmethod
+    def backward(ctx, grad_output):
+        neuron = ctx.neuron
+
+        pre_unpredict = neuron.simulator.prob(neuron.output_id)
+        neuron.unpredict()
+        post_unpredict = neuron.simulator.prob(neuron.output_id)
+        reverse_delta = pre_unpredict - post_unpredict
+
+        grad = reverse_delta - ctx.delta
+
+        return (
+            torch.tensor([grad], dtype=torch.float32) if _IS_TORCH_AVAILABLE else grad
+        )
+
+
+class QrackNeuronTorchLayer(nn.Module if _IS_TORCH_AVAILABLE else object):
+    """Torch layer wrapper for QrackNeuron (with power set of neurons between inputs and outputs)"""
+
+    def __init__(
+        self,
+        simulator,
+        input_indices,
+        output_indices,
+        activation=int(NeuronActivationFn.Generalized_Logistic),
+        parameters=None,
+    ):
+        """
+        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_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)
+        """
+        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
+            ]
+        )
+
+        # Set Qrack's internal parameters:
+        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)
+            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
+
+        # Assume quantum inputs already loaded into simulator state
+        for neuron_wrapper in self.neurons:
+            self.fn(neuron_wrapper.neuron)
+
+        # 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]
+
+        return torch.tensor(outputs, dtype=torch.float32)