:py:mod:`pyqrack.qrack_neuron`
==============================

.. py:module:: pyqrack.qrack_neuron


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   pyqrack.qrack_neuron.QrackNeuron




.. py:class:: QrackNeuron(simulator, controls, target, activation_fn=NeuronActivationFn.Sigmoid, alpha=1.0, tolerance=sys.float_info.epsilon, _init=True)


   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.

   .. attribute:: nid

      Qrack ID of this neuron

      :type: int

   .. attribute:: simulator

      Simulator instance for all synaptic clefts of the neuron

      :type: QrackSimulator

   .. attribute:: controls

      Indices of all "control" qubits, for neuron input

      :type: list(int)

   .. attribute:: target

      Index of "target" qubit, for neuron output

      :type: int

   .. attribute:: tolerance

      Rounding tolerance

      :type: double

   .. py:method:: _get_error()


   .. py:method:: _throw_if_error()


   .. py:method:: __del__()


   .. py:method:: clone()

      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.


   .. py:method:: _ulonglong_byref(a)


   .. py:method:: _real1_byref(a)


   .. py:method:: set_angles(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.

      :param a: List of input permutation angles
      :type a: list(double)

      :raises ValueError: Angles 'a' in QrackNeuron.set_angles() must contain at least (2 ** len(self.controls)) elements.
      :raises RuntimeError: QrackSimulator raised an exception.


   .. py:method:: get_angles()

      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.


   .. py:method:: set_alpha(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.


   .. py:method:: set_activation_fn(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.


   .. py:method:: predict(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.

      :param e: If False, predict the opposite
      :type e: bool
      :param r: If True, start by resetting the output to 50/50
      :type r: bool

      :raises RuntimeError: QrackNeuron C++ library raised an exception.


   .. py:method:: unpredict(e=True)

      Uncompute a prediction

      Uncompute a 'prediction' of the anticipated output, based on
      input and training.

      :param e: If False, unpredict the opposite
      :type e: bool

      :raises RuntimeError: QrackNeuron C++ library raised an exception.


   .. py:method:: learn_cycle(e=True)

      Run a learning cycle

      A learning cycle consists of predicting a result, saving the
      classical outcome, and uncomputing the prediction.

      :param e: If False, predict the opposite
      :type e: bool

      :raises RuntimeError: QrackNeuron C++ library raised an exception.


   .. py:method:: learn(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.

      :param eta: Training volatility, 0 to 1
      :type eta: double
      :param e: If False, predict the opposite
      :type e: bool
      :param r: If True, start by resetting the output to 50/50
      :type r: bool

      :raises RuntimeError: QrackNeuron C++ library raised an exception.


   .. py:method:: learn_permutation(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.

      :param eta: Training volatility, 0 to 1
      :type eta: double
      :param e: If False, predict the opposite
      :type e: bool
      :param r: If True, start by resetting the output to 50/50
      :type r: bool

      :raises RuntimeError: QrackNeuron C++ library raised an exception.