Metadata-Version: 2.2
Name: qmath-a7s
Version: 0.1.1
Summary: Quantum Mathematics Framework
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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`:

```bash
pip install .
```

For developer / editable installations:

```bash
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

```python
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)

```python
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.
