# {{PROJECT_NAME}}

{{PROJECT_DESCRIPTION}}

Generated with [AgentBible](https://github.com/rylanmalarchick/research-code-principles) using the `python-quantum` template.

## Quick Start

```bash
# Activate virtual environment (created by bible init)
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Optional: Install Qiskit support
pip install -e ".[qiskit]"

# Optional: Install Cirq support
pip install -e ".[cirq]"

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy src/
```

## Project Structure

```
{{PROJECT_NAME}}/
|-- src/                       # Source code
|   |-- __init__.py
|   |-- validation.py          # Quantum validation utilities
|   |-- gates.py               # Common quantum gates
|   +-- circuits.py            # Circuit construction utilities
|-- tests/                     # Test suite
|   |-- conftest.py            # Quantum fixtures
|   +-- test_validation.py     # Validation tests
|-- .cursorrules               # AI agent instructions
|-- pyproject.toml             # Project configuration
+-- README.md                  # This file
```

## Quantum Validation

The `validation.py` module provides comprehensive quantum constraint checking:

```python
from src.validation import (
    check_unitarity,
    check_normalized,
    check_density_matrix,
    check_hermitian,
    check_probabilities,
    check_cptp,
    check_qubit_dimension,
)

# Validate quantum operations
check_unitarity(gate_matrix)         # U dagger U = I
check_normalized(state_vector)       # <psi|psi> = 1
check_density_matrix(rho)            # Hermitian, trace=1, PSD
check_hermitian(hamiltonian)         # H = H dagger
check_probabilities(measurement)     # non-negative, sum=1
check_cptp(kraus_operators)          # Valid quantum channel
check_qubit_dimension(matrix, n=2)   # Dimension is 2^n
```

## Quantum Gates

The `gates.py` module provides standard quantum gates:

```python
from src.gates import (
    pauli_x, pauli_y, pauli_z,    # Single-qubit Paulis
    hadamard, phase, t_gate,       # Common single-qubit gates
    rx, ry, rz,                    # Rotation gates
    cnot, cz, swap,                # Two-qubit gates
    controlled,                    # Make any gate controlled
    tensor,                        # Tensor product helper
)
```

## Development

### Running Tests

```bash
pytest                      # Run all tests
pytest -v                   # Verbose output
pytest -m "not slow"        # Skip slow tests
pytest -m "not requires_qiskit"  # Skip Qiskit tests
pytest --cov=src            # With coverage
```

### Code Quality

```bash
ruff check .                # Lint
ruff format .               # Format
mypy src/                   # Type check
```

## Quantum Computing Resources

- [Qiskit Textbook](https://qiskit.org/textbook/)
- [Cirq Documentation](https://quantumai.google/cirq)
- [Nielsen & Chuang](https://www.cambridge.org/core/books/quantum-computation-and-quantum-information/)

## License

MIT - Created {{YEAR}}
