qmath-a7s 0.1.1

Quantum Mathematics Framework

QMath: Quantum Mathematics Framework

QMath is a high-performance, production-ready Quantum Mathematics and Simulation framework. It features a templated, multi-threaded C++20 core bound seamlessly to a pythonic interface using pybind11 and scikit-build-core.

By combining the speed of optimized C++ (leveraging cache-friendly layouts and OpenMP parallelism) with the agility of Python, QMath enables rapid prototyping of quantum states, custom gates, circuits, and advanced quantum algorithms.

---

Key Features

• Core Linear Algebra: High-performance Vector, Matrix, and multi-dimensional Tensor core types supporting float32, float64, complex64, and complex128.
• Advanced Decompositions: LU, QR, Cholesky, and Jacobi Eigenvalue solver (Hermitian/Symmetric).
• Quantum Mechanics Core:
  • Full support for both Pure States (state vectors) and Mixed States (density matrices).
  • Expectation values, von Neumann entropy, purity, quantum fidelity, and partial traces.
  • State factories for single qubits, Bell states, GHZ states, W states, and Haar random states.
• Circuit Simulation Engine:
  • Full single-qubit and multi-qubit gate sets.
  • Evolutionary simulation (unitary application for state vectors and density matrices).
  • Single-qubit measurement collapse and multi-shot outcome sampling.
  • Text-based ASCII circuit visualizer.
• Quantum Algorithms:
  • Quantum Fourier Transform (QFT).
  • Grover's Search Algorithm.
  • Deutsch-Jozsa Algorithm (Constant vs. Balanced oracle testing).
  • Variational Quantum Eigensolver (VQE) bound to C++ Newton-Raphson parameter minimizers.
• Numerical Formulas: Central/second-order differentiation, Jacobian generation, trapezoidal/Simpson integration, gradient descent, and Conjugate Gradient linear solvers.
• Symbolic Math Engine: Expression tree formulation for symbols, constants, and basic algebra.

---

Installation

Prerequisites

QMath requires a C++20 compatible compiler (e.g., GCC 10+, MSVC 2019+, or Clang 10+).

Building from Source

Install the package directly using pip:

pip install .

For developer / editable installations:

pip install -e .

Note: scikit-build-core will automatically fetch cmake and ninja dependencies during the build.

---

Quick Start Examples

1. Simulating a Bell State

from qmath import QuantumCircuit

# 1. Create a 2-qubit circuit
qc = QuantumCircuit(2)

# 2. Apply Hadamard on qubit 0 and CNOT controlled on 0 targeting 1
qc.h(0)
qc.cx(0, 1)

# 3. Print the ASCII diagram
print("Circuit Diagram:")
print(qc.draw())

# 4. Simulate the statevector evolution
state = qc.simulate()
print("\nFinal State Vector:")
print(state)

# 5. Sample measurement outcomes (1024 shots)
counts = qc.sample(shots=1024)
print("\nMeasurement counts:")
print(counts)

2. Variational Quantum Eigensolver (VQE)

import numpy as np
from qmath import Matrix
from qmath.formulas.algorithms import vqe

# Create a sample diagonal Hamiltonian where the ground state energy is 0.5
H_data = np.diag([1.5, 2.5, 3.5, 0.5])
H = Matrix(H_data)

# Minimize expectation using VQE with hardware-efficient ansatz
ground_energy = vqe(H, learning_rate=0.05, tol=1e-5, max_iter=50)

print(f"Calculated Ground State Energy: {ground_energy}")
print(f"Exact Ground State Energy: {min(np.diagonal(H_data))}")

---

License

This project is licensed under the MIT License.