qumat 0.0.1__py3-none-any.whl → 0.5.0rc1__py3-none-any.whl

qumat/qumat.py

@@ -16,75 +16,549 @@
 #
 from importlib import import_module
 
+
 class QuMat:
+    """Unified interface for quantum circuit operations across multiple backends.
+
+    Provides a consistent API for creating and manipulating quantum circuits
+    using different quantum computing backends (Qiskit, Cirq, Amazon Braket).
+    Abstracts backend-specific details for gate operations, circuit execution,
+    and state measurement.
+
+    :param backend_config: Configuration dictionary for the quantum backend.
+        Must contain ``backend_name`` (str) and ``backend_options`` (dict).
+        The ``backend_options`` should include ``simulator_type`` and ``shots``.
+    :type backend_config: dict
+    """
+
     def __init__(self, backend_config):
+        """Create a QuMat instance with the specified backend configuration.
+
+        :param backend_config: Configuration dictionary containing backend name
+            and options. Required keys:
+            - ``backend_name``: Name of the backend (e.g., "qiskit", "cirq", "amazon_braket")
+            - ``backend_options``: Dictionary with backend-specific options
+        :type backend_config: dict
+        :raises ImportError: If the specified backend module cannot be imported.
+        :raises ValueError: If backend_config is not a dictionary.
+        :raises KeyError: If required configuration keys are missing.
+        """
+        if not isinstance(backend_config, dict):
+            raise ValueError(
+                f"backend_config must be a dictionary, got {type(backend_config).__name__}"
+            )
+
+        if "backend_name" not in backend_config:
+            raise KeyError(
+                "backend_config is missing required key 'backend_name'. "
+                "Please provide a backend name (e.g., 'qiskit', 'cirq', 'amazon_braket')"
+            )
+
+        if "backend_options" not in backend_config:
+            raise KeyError(
+                "backend_config is missing required key 'backend_options'. "
+                "Please provide a dictionary with backend-specific options "
+            )
+
         self.backend_config = backend_config
-        self.backend_name = backend_config['backend_name']
-        self.backend_module = import_module(f".{self.backend_name}_backend", package="qumat")
+        self.backend_name = backend_config["backend_name"]
+        self.backend_module = import_module(
+            f".{self.backend_name}_backend", package="qumat"
+        )
         self.backend = self.backend_module.initialize_backend(backend_config)
         self.circuit = None
+        self.num_qubits = None
         self.parameters = {}
 
-    def create_empty_circuit(self, num_qubits):
+    def create_empty_circuit(self, num_qubits: int | None = None):
+        """Create an empty quantum circuit with the specified number of qubits.
+
+        Must be called before applying any gates or executing operations.
+
+        :param num_qubits: Number of qubits in the circuit. If ``None``,
+            creates a circuit without pre-allocated qubits.
+        :type num_qubits: int | None, optional
+        """
+        self.num_qubits = num_qubits
         self.circuit = self.backend_module.create_empty_circuit(num_qubits)
 
+    def _ensure_circuit_initialized(self):
+        """Ensure the circuit has been created before operations.
+
+        Checks if the circuit has been initialized via ``create_empty_circuit()``.
+        Raises ``RuntimeError`` if not initialized.
+
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        if self.circuit is None:
+            raise RuntimeError(
+                "circuit not initialized. call create_empty_circuit(num_qubits) "
+                "before applying gates or executing operations."
+            )
+
+    def _validate_qubit_index(self, qubit_index, param_name="qubit_index"):
+        """validate qubit index is within circuit bounds.
+
+        :param qubit_index: the qubit index to validate.
+        :type qubit_index: int
+        :param param_name: name of the parameter for error messages.
+        :type param_name: str
+        :raises TypeError: if qubit_index is not an integer.
+        :raises ValueError: if qubit_index is negative or out of range.
+        """
+        if not isinstance(qubit_index, int):
+            raise TypeError(
+                f"{param_name} must be an integer, got {type(qubit_index).__name__}"
+            )
+        if qubit_index < 0:
+            raise ValueError(f"{param_name} cannot be negative, got {qubit_index}")
+        if self.num_qubits is not None and qubit_index >= self.num_qubits:
+            raise ValueError(
+                f"{param_name} {qubit_index} out of range for circuit with "
+                f"{self.num_qubits} qubits (valid range: 0-{self.num_qubits - 1})"
+            )
+
     def apply_not_gate(self, qubit_index):
+        """Apply a NOT gate (Pauli-X gate) to the specified qubit.
+
+        Flips the qubit state from |0⟩ to |1⟩ or |1⟩ to |0⟩.
+        Equivalent to the Pauli-X gate.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self.backend_module.apply_not_gate(self.circuit, qubit_index)
 
     def apply_hadamard_gate(self, qubit_index):
+        """Apply a Hadamard gate to the specified qubit.
+
+        Creates a superposition state, transforming |0⟩ to (|0⟩ + |1⟩)/√2
+        and |1⟩ to (|0⟩ - |1⟩)/√2.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self.backend_module.apply_hadamard_gate(self.circuit, qubit_index)
 
     def apply_cnot_gate(self, control_qubit_index, target_qubit_index):
-        self.backend_module.apply_cnot_gate(self.circuit, control_qubit_index, target_qubit_index)
+        """Apply a Controlled-NOT (CNOT) gate between two qubits.
+
+        Fundamental for entangling qubits. Flips the target qubit if and only
+        if the control qubit is in the |1⟩ state.
 
-    def apply_toffoli_gate(self, control_qubit_index1, control_qubit_index2, target_qubit_index):
-        self.backend_module.apply_toffoli_gate(self.circuit, control_qubit_index1, control_qubit_index2, target_qubit_index)
+        :param control_qubit_index: Index of the control qubit.
+        :type control_qubit_index: int
+        :param target_qubit_index: Index of the target qubit.
+        :type target_qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(control_qubit_index, "control_qubit_index")
+        self._validate_qubit_index(target_qubit_index, "target_qubit_index")
+        self.backend_module.apply_cnot_gate(
+            self.circuit, control_qubit_index, target_qubit_index
+        )
+
+    def apply_toffoli_gate(
+        self, control_qubit_index1, control_qubit_index2, target_qubit_index
+    ):
+        """Apply a Toffoli gate (CCX gate) to three qubits.
+
+        Acts as a quantum AND gate. Flips the target qubit if and only if
+        both control qubits are in the |1⟩ state.
+
+        :param control_qubit_index1: Index of the first control qubit.
+        :type control_qubit_index1: int
+        :param control_qubit_index2: Index of the second control qubit.
+        :type control_qubit_index2: int
+        :param target_qubit_index: Index of the target qubit.
+        :type target_qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(control_qubit_index1, "control_qubit_index1")
+        self._validate_qubit_index(control_qubit_index2, "control_qubit_index2")
+        self._validate_qubit_index(target_qubit_index, "target_qubit_index")
+        self.backend_module.apply_toffoli_gate(
+            self.circuit, control_qubit_index1, control_qubit_index2, target_qubit_index
+        )
 
     def apply_swap_gate(self, qubit_index1, qubit_index2):
+        """Swap the states of two qubits.
+
+        :param qubit_index1: Index of the first qubit.
+        :type qubit_index1: int
+        :param qubit_index2: Index of the second qubit.
+        :type qubit_index2: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index1, "qubit_index1")
+        self._validate_qubit_index(qubit_index2, "qubit_index2")
         self.backend_module.apply_swap_gate(self.circuit, qubit_index1, qubit_index2)
 
+    def apply_cswap_gate(
+        self, control_qubit_index, target_qubit_index1, target_qubit_index2
+    ):
+        """Apply a controlled-SWAP (Fredkin) gate.
+
+        Swaps the states of two target qubits if and only if the control
+        qubit is in the |1⟩ state.
+
+        :param control_qubit_index: Index of the control qubit.
+        :type control_qubit_index: int
+        :param target_qubit_index1: Index of the first target qubit.
+        :type target_qubit_index1: int
+        :param target_qubit_index2: Index of the second target qubit.
+        :type target_qubit_index2: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(control_qubit_index, "control_qubit_index")
+        self._validate_qubit_index(target_qubit_index1, "target_qubit_index1")
+        self._validate_qubit_index(target_qubit_index2, "target_qubit_index2")
+        self.backend_module.apply_cswap_gate(
+            self.circuit, control_qubit_index, target_qubit_index1, target_qubit_index2
+        )
+
     def apply_pauli_x_gate(self, qubit_index):
+        """Apply a Pauli-X gate to the specified qubit.
+
+        Equivalent to the NOT gate. Flips the qubit state from |0⟩ to |1⟩
+        or |1⟩ to |0⟩.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self.backend_module.apply_pauli_x_gate(self.circuit, qubit_index)
 
     def apply_pauli_y_gate(self, qubit_index):
+        """Apply a Pauli-Y gate to the specified qubit.
+
+        Rotates the qubit around the Y-axis of the Bloch sphere, affecting
+        both phase and amplitude.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self.backend_module.apply_pauli_y_gate(self.circuit, qubit_index)
 
     def apply_pauli_z_gate(self, qubit_index):
+        """Apply a Pauli-Z gate to the specified qubit.
+
+        Rotates the qubit around the Z-axis of the Bloch sphere, altering
+        the phase without changing the amplitude.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self.backend_module.apply_pauli_z_gate(self.circuit, qubit_index)
 
+    def apply_t_gate(self, qubit_index):
+        """Apply a T-gate (π/8 gate) to the specified qubit.
+
+        Applies a relative pi/4 phase (multiplies the |1> state by e^{i*pi/4}).
+        Essential for universal quantum computation when combined with
+        Hadamard and CNOT gates.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
+        self.backend_module.apply_t_gate(self.circuit, qubit_index)
+
     def execute_circuit(self, parameter_values=None):
+        """Execute the quantum circuit and return the measurement results.
+
+        Runs the circuit on the configured backend. For parameterized circuits,
+        provide parameter values to bind before execution.
+
+        :param parameter_values: Dictionary mapping parameter names to numerical
+            values. Binds these values to circuit parameters before execution.
+        :type parameter_values: dict, optional
+        :returns: Measurement results. Format depends on the backend:
+            - Qiskit/Braket: Dictionary with state strings as keys and counts as values
+            - Cirq: List of dictionaries with integer states as keys
+        :rtype: dict | list[dict]
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        if self.num_qubits == 0:
+            shots = self.backend_config["backend_options"].get("shots", 1)
+            if self.backend_name == "cirq":
+                return [{0: shots}]
+            else:
+                return {"": shots}
+
         if parameter_values:
             self.bind_parameters(parameter_values)
-        self.backend_config['parameter_values'] = self.parameters  # Pass parameters
-        return self.backend_module.execute_circuit(self.circuit, self.backend, self.backend_config)
+
+        # Only pass bound parameters (non-None values) to backend
+        bound_parameters = {
+            param: value
+            for param, value in self.parameters.items()
+            if value is not None
+        }
+
+        # Check if there are unbound parameters in the circuit
+        if self.parameters and len(bound_parameters) < len(self.parameters):
+            unbound_params = [
+                p for p in self.parameters.keys() if self.parameters[p] is None
+            ]
+            raise ValueError(
+                f"Circuit contains unbound parameters: {unbound_params}. "
+                f"Please provide parameter_values when executing the circuit."
+            )
+
+        self.backend_config["parameter_values"] = bound_parameters
+        return self.backend_module.execute_circuit(
+            self.circuit, self.backend, self.backend_config
+        )
 
     def bind_parameters(self, parameter_values):
+        """Bind numerical values to circuit parameters.
+
+        Assigns numerical values to symbolic parameters defined in parameterized
+        gates.
+
+        :param parameter_values: Dictionary mapping parameter names to numerical
+            values.
+        :type parameter_values: dict
+        :raises ValueError: If a parameter name is not found in the circuit's
+            parameter list.
+        """
         for param, value in parameter_values.items():
-            if param in self.parameters:
-                self.parameters[param] = value
+            if param not in self.parameters:
+                raise ValueError(
+                    f"parameter '{param}' not found in circuit. "
+                    f"available parameters: {list(self.parameters.keys())}"
+                )
+            self.parameters[param] = value
 
-    # placeholder method for use in the testing suite
     def get_final_state_vector(self):
-        return self.backend_module.get_final_state_vector(self.circuit, self.backend, self.backend_config)
+        """Return the final state vector of the quantum circuit.
 
-    def draw(self):
+        The complete quantum state vector after circuit execution,
+        representing the full quantum state of all qubits.
+
+        :returns: The final state vector as a numpy array.
+        :rtype: numpy.ndarray
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        return self.backend_module.get_final_state_vector(
+            self.circuit, self.backend, self.backend_config
+        )
+
+    def draw_circuit(self):
+        """Visualize the quantum circuit.
+
+        Generates a visual representation of the circuit. The output format
+        depends on the backend implementation.
+
+        :returns: Circuit visualization. The exact type depends on the backend.
+        :rtype: str | object
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
         return self.backend_module.draw_circuit(self.circuit)
 
+    def draw(self):
+        """Alias for draw_circuit() for convenience.
+
+        Provides a shorter method name that matches common quantum computing
+        library conventions and documentation examples.
+
+        :returns: Circuit visualization. The exact type depends on the backend.
+        :rtype: str | object
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        return self.draw_circuit()
+
     def apply_rx_gate(self, qubit_index, angle):
+        """Apply a rotation around the X-axis to the specified qubit.
+
+        Rotates the qubit by the given angle around the X-axis of the Bloch
+        sphere. The angle can be a static value or a parameter name for
+        parameterized circuits.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :param angle: Rotation angle in radians. Can be a float or a string
+            parameter name.
+        :type angle: float | str
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self._handle_parameter(angle)
         self.backend_module.apply_rx_gate(self.circuit, qubit_index, angle)
 
     def apply_ry_gate(self, qubit_index, angle):
+        """Apply a rotation around the Y-axis to the specified qubit.
+
+        Rotates the qubit by the given angle around the Y-axis of the Bloch
+        sphere. The angle can be a static value or a parameter name for
+        parameterized circuits.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :param angle: Rotation angle in radians. Can be a float or a string
+            parameter name.
+        :type angle: float | str
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self._handle_parameter(angle)
         self.backend_module.apply_ry_gate(self.circuit, qubit_index, angle)
 
     def apply_rz_gate(self, qubit_index, angle):
+        """Apply a rotation around the Z-axis to the specified qubit.
+
+        Rotates the qubit by the given angle around the Z-axis of the Bloch
+        sphere. The angle can be a static value or a parameter name for
+        parameterized circuits.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :param angle: Rotation angle in radians. Can be a float or a string
+            parameter name.
+        :type angle: float | str
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self._handle_parameter(angle)
         self.backend_module.apply_rz_gate(self.circuit, qubit_index, angle)
 
     def _handle_parameter(self, param_name):
+        """Register parameter names when parameterized gates are applied.
+
+        Automatically adds string parameter names to the parameters dictionary
+        if not already registered.
+
+        :param param_name: Parameter name to handle. If it's a string,
+            registers it as a parameter.
+        :type param_name: str | float
+        """
         if isinstance(param_name, str) and param_name not in self.parameters:
             self.parameters[param_name] = None
 
     def apply_u_gate(self, qubit_index, theta, phi, lambd):
+        """Apply a U gate (universal single-qubit gate) to the specified qubit.
+
+        A universal single-qubit gate parameterized by three angles (theta,
+        phi, lambd) that can represent any single-qubit unitary operation.
+
+        :param qubit_index: Index of the qubit.
+        :type qubit_index: int
+        :param theta: First rotation angle in radians.
+        :type theta: float
+        :param phi: Second rotation angle in radians.
+        :type phi: float
+        :param lambd: Third rotation angle in radians.
+        :type lambd: float
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        self._ensure_circuit_initialized()
+        self._validate_qubit_index(qubit_index)
         self.backend_module.apply_u_gate(self.circuit, qubit_index, theta, phi, lambd)
+
+    def swap_test(self, ancilla_qubit, qubit1, qubit2):
+        """Implement the swap test circuit for measuring overlap between two quantum states.
+
+        Measures the inner product between the states on ``qubit1`` and ``qubit2``.
+        The probability of measuring the ancilla qubit in state |0⟩ is related
+        to the overlap as: P(0) = (1 + |⟨ψ|φ⟩|²) / 2
+
+        :param ancilla_qubit: Index of the ancilla qubit (should be initialized to |0⟩).
+        :type ancilla_qubit: int
+        :param qubit1: Index of the first qubit containing state |ψ⟩.
+        :type qubit1: int
+        :param qubit2: Index of the second qubit containing state |φ⟩.
+        :type qubit2: int
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        # Apply Hadamard to ancilla qubit
+        self.apply_hadamard_gate(ancilla_qubit)
+
+        # Apply controlled-SWAP (Fredkin gate) with ancilla as control
+        self.apply_cswap_gate(ancilla_qubit, qubit1, qubit2)
+
+        # Apply Hadamard to ancilla qubit again
+        self.apply_hadamard_gate(ancilla_qubit)
+
+    def measure_overlap(self, qubit1, qubit2, ancilla_qubit=0):
+        """Measure the overlap (fidelity) between two quantum states using the swap test.
+
+        Creates a swap test circuit to calculate the similarity between the
+        quantum states on ``qubit1`` and ``qubit2``. Returns the squared overlap
+        |⟨ψ|φ⟩|², which represents the fidelity between the two states.
+
+        The swap test measures P(ancilla=0), related to overlap as:
+        P(0) = (1 + |⟨ψ|φ⟩|²) / 2
+
+        For certain states (especially identical excited states), global phase
+        effects may cause the ancilla to measure predominantly |1⟩ instead of |0⟩.
+        This method handles both cases by taking the measurement probability
+        closer to 1.
+
+        :param qubit1: Index of the first qubit containing state |ψ⟩.
+        :type qubit1: int
+        :param qubit2: Index of the second qubit containing state |φ⟩.
+        :type qubit2: int
+        :param ancilla_qubit: Index of the ancilla qubit. Default is 0. Should be
+            initialized to |0⟩.
+        :type ancilla_qubit: int, optional
+        :returns: The squared overlap |⟨ψ|φ⟩|² between the two states (fidelity),
+            clamped to the range [0.0, 1.0].
+        :rtype: float
+        :raises RuntimeError: If the circuit has not been initialized.
+        """
+        # Perform the swap test
+        self.swap_test(ancilla_qubit, qubit1, qubit2)
+        results = self.execute_circuit()
+
+        # Calculate the probability of measuring ancilla in |0> state
+        prob_zero = self.calculate_prob_zero(results, ancilla_qubit)
+        prob_zero_or_one = max(prob_zero, 1 - prob_zero)
+        overlap_squared = 2 * prob_zero_or_one - 1
+        overlap_squared = max(0.0, min(1.0, overlap_squared))
+
+        return overlap_squared
+
+    def calculate_prob_zero(self, results, ancilla_qubit):
+        """Calculate the probability of measuring the ancilla qubit in |0⟩ state.
+
+        Delegates to the backend-specific implementation. Different backends
+        may use different qubit ordering conventions (little-endian vs big-endian).
+
+        :param results: Measurement results from ``execute_circuit()``. Format
+            depends on the backend.
+        :type results: dict | list[dict]
+        :param ancilla_qubit: Index of the ancilla qubit.
+        :type ancilla_qubit: int
+        :returns: Probability of measuring the ancilla qubit in |0⟩ state.
+        :rtype: float
+        """
+        return self.backend_module.calculate_prob_zero(
+            results, ancilla_qubit, self.num_qubits
+        )

qumat-0.5.0rc1.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: qumat
+Version: 0.5.0rc1
+Summary: A library for composing quantum machine learning.
+Author-email: Apache Mahout <dev@mahout.apache.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: <3.13,>=3.10
+Requires-Dist: amazon-braket-sdk<2.0,>=1.108.0
+Requires-Dist: cirq<1.6.0,>=1.5.0
+Requires-Dist: qiskit-aer<0.18.0,>=0.17.2
+Requires-Dist: qiskit<3.0.0,>=2.2.0
+Requires-Dist: sympy<2.0,>=1.14.0
+Provides-Extra: qdp
+Requires-Dist: qumat-qdp; extra == 'qdp'
+Description-Content-Type: text/markdown
+
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Mahout
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Python](https://img.shields.io/badge/Python-3.10--3.12-blue.svg)](https://www.python.org/)
+[![GitHub Stars](https://img.shields.io/github/stars/apache/mahout.svg)](https://github.com/apache/mahout/stargazers)
+[![GitHub Contributors](https://img.shields.io/github/contributors/apache/mahout.svg)](https://github.com/apache/mahout/graphs/contributors)
+
+The goal of the Apache Mahout™ project is to build an environment for quickly creating scalable, performant machine learning applications.\
+For additional information about Mahout, visit the [Mahout Home Page](http://mahout.apache.org/)
+
+## Qumat
+
+<p align="center">
+  <img src="docs/assets/mascot_with_text.png" width="400" alt="Apache Mahout">
+</p>
+
+Qumat is a high-level Python library for quantum computing that provides:
+
+- **Quantum Circuit Abstraction** - Build quantum circuits with standard gates (Hadamard, CNOT, Pauli, etc.) and run them on Qiskit, Cirq, or Amazon Braket with a single unified API. Write once, execute anywhere. Check out [basic gates](docs/basic_gates.md) for a quick introduction to the basic gates supported across all backends.
+- **QDP (Quantum Data Plane)** - Encode classical data into quantum states using GPU-accelerated kernels. Zero-copy tensor transfer via DLPack lets you move data between PyTorch, NumPy, and TensorFlow without overhead.
+
+## Quick Start
+
+```bash
+git clone https://github.com/apache/mahout.git
+cd mahout
+pip install uv
+uv sync                     # Core Qumat
+uv sync --extra qdp         # With QDP (requires CUDA GPU)
+```
+
+### Qumat: Run a Quantum Circuit
+
+```python
+from qumat import QuMat
+
+qumat = QuMat({"backend_name": "qiskit", "backend_options": {"simulator_type": "aer_simulator"}})
+qumat.create_empty_circuit(num_qubits=2)
+qumat.apply_hadamard_gate(0)
+qumat.apply_cnot_gate(0, 1)
+qumat.execute_circuit()
+```
+
+### QDP: Encode data for Quantum ML
+
+```python
+import qumat.qdp as qdp
+
+engine = qdp.QdpEngine(device_id=0)
+qtensor = engine.encode([1.0, 2.0, 3.0, 4.0], num_qubits=2, encoding_method="amplitude")
+```
+
+## Roadmap
+
+### 2024
+- [x] Transition of Classic to maintenance mode
+- [x] Integration of Qumat with hardened (tests, docs, CI/CD) Cirq, Qiskit, and Braket backends
+- [x] Integration with Amazon Braket
+- [x] [Public talk about Qumat](https://2024.fossy.us/schedule/presentation/265/)
+
+### 2025
+- [x] [FOSDEM talk](https://fosdem.org/2025/schedule/event/fosdem-2025-5298-introducing-qumat-an-apache-mahout-joint-/)
+- [x] QDP: Foundation & Infrastructure (Rust workspace, build configuration)
+- [x] QDP: Core Implementation (CUDA kernels, CPU preprocessing, GPU memory management)
+- [x] QDP: Zero-copy and Safety (DLManagedTensor, DLPack structures)
+- [x] QDP: Python Binding (PyO3 wrapping, DLPack protocol)
+
+### Q1 2026
+- [ ] QDP: Input Format Support (PyTorch, NumPy, TensorFlow integration)
+- [ ] QDP: Verification and Testing (device testing, benchmarking)
+- [ ] QDP: Additional Encoders (angle/basis encoding, multi-GPU optimization)
+- [ ] QDP: Integration & Release (documentation, example notebooks, PyPI publishing)
+
+## Legal
+Please see the `NOTICE.txt` included in this directory for more information.

qumat-0.5.0rc1.dist-info/RECORD

@@ -0,0 +1,11 @@
+qumat/__init__.py,sha256=HweBfNndHmuHN3X2t0JR9vP9wsfDqkjSzBbEdS0XfF0,854
+qumat/amazon_braket_backend.py,sha256=dDCn4oXsZwQqJdQIMWQD29HiNGECxYulklEiqFZsnPo,5787
+qumat/cirq_backend.py,sha256=jBdNQBi_86Z4cloDV1LXmhXRl7ae3mQbwf30AOjNrfY,6490
+qumat/qdp.py,sha256=gKiQjlrB_oFwm--_LdJKPgO_XvXfhdV6XXtWHonbtFg,2332
+qumat/qiskit_backend.py,sha256=ZjNbu3ToN9FLVL_C_3HLp5tS_wib0up48ibmUiq3VTI,6996
+qumat/qumat.py,sha256=pzpi015z9MwIgrRok1MFJjcKfLGHVBFbzsswJEcdwEo,24308
+qumat-0.5.0rc1.dist-info/METADATA,sha256=0IcBFH6ADR1rjAiFzaMtYFxCFLYVv3snED7k9r7GTtA,4606
+qumat-0.5.0rc1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+qumat-0.5.0rc1.dist-info/licenses/LICENSE,sha256=PM3t-YVh-GyXESTynXe-orGOAJ9z1xBgh0mbsLdn0Co,12628
+qumat-0.5.0rc1.dist-info/licenses/NOTICE,sha256=TBC-GYUVZqnqxC23u5wXAUvyMwYXx0-H4_NT5ASLmvM,295
+qumat-0.5.0rc1.dist-info/RECORD,,