QUICK_START.md

# Quick Start Guide: SHA-520 Quantum Cryptanalysis

## Installation

```bash

# Navigate to project directory

cd C:\Users\jessi\Desktop\topological-quantum-computer



# Add to Python path

export PYTHONPATH="${PYTHONPATH}:$(pwd)"

```

## Quick Examples

### SHA-520 Reference Implementation

```python

from python.classical import SHA520



# Create hasher with 80 rounds

hasher = SHA520(rounds=80)



# Hash data

digest = hasher.digest(b"hello world")

print(digest.hex())  # 520-bit (65-byte) hash



# Use reduced rounds for faster testing

hasher_4 = SHA520(rounds=4)

digest_4 = hasher_4.digest(b"test")

```

### Toy SHA-520 (Fast Testing)

```python

from python.classical import ToySHA520



# Create toy hasher: 4 rounds, 32-bit words, 128-bit output

toy = ToySHA520(rounds=4)



# Hash data

digest = toy.digest(b"test")  # 16-byte (128-bit) hash

print(digest.hex())

```

### Classical Attacks

```python

from python.classical import measure_classical_complexity, brute_force_preimage



# Estimate complexity

complexity = measure_classical_complexity(rounds=80, target_bits=64)

print(f"Preimage trials: {complexity['preimage_trials']:.2e}")

print(f"Preimage time: {complexity['preimage_time_years']} years")



# Brute force preimage search

target = SHA520().digest(b"secret")

result, trials, elapsed = brute_force_preimage(target, SHA520().digest, max_trials=10000)

```

### Quantum Circuits

```python

from python.quantum import ReversibleSHA520, GroverSHA520



# Build reversible SHA-520 oracle

rev_sha = ReversibleSHA520(rounds=4, n_qubits_message=32)

oracle = rev_sha.build_oracle(b'\x00' * 64)

print(f"Oracle circuit: {oracle}")

print(f"Resources: {rev_sha.resource_estimate()}")



# Build Grover circuit

grover = GroverSHA520(rounds=4, target_hash=b'\x00' * 64, n_qubits_message=32)

circuit = grover.build_grover_preimage()

resources = grover.estimate_resources()

print(f"Grover iterations: {resources['grover_iterations']}")

print(f"Circuit depth: {resources['total_circuit_depth']}")

```

### Speedup Analysis

```python

from python.quantum import grover_speedup_vs_classical, estimate_resources



# Compare quantum vs classical

speedup = grover_speedup_vs_classical(target_bits=64, rounds=80)

print(f"Speedup: {speedup['speedup_factor']:.2e}x")

print(f"Grover time: {speedup['grover_time_sec']:.2e} sec")

print(f"Classical time: {speedup['classical_time_sec']:.2e} sec")



# Resource requirements

resources = estimate_resources(rounds=80, target_bits=64)

print(f"Logical qubits: {resources['total_logical_qubits']}")

print(f"Physical qubits (with error correction): {resources['total_logical_qubits']}")

```

### Simulators

```python

from python.simulators import TensorNetworkSimulator, estimate_circuit_resources



# Tensor network simulator

sim = TensorNetworkSimulator(n_qubits=8)

print(f"Created {sim.n_qubits}-qubit simulator")



# Qiskit resource estimation

resources = estimate_circuit_resources(rounds=4, target_bits=32)

print(f"Circuit depth: {resources['total_depth']}")

print(f"Gates: {resources['total_gates']}")



# Run with Qiskit (if installed)

try:

    from python.simulators import run_grover_simulation

    result = run_grover_simulation(rounds=4, target_bits=8, shots=1024)

    print(f"Success rate: {result['success_rate']:.2%}")

except ImportError:

    print("Qiskit not available")

```

## Module Organization

```

python/

├── classical/

│   ├── sha520_ref.py           # SHA-520 hash function

│   ├── classical_baselines.py  # Classical attacks & complexity

│   └── toy_permutations.py     # Reduced-round testing

├── quantum/

│   ├── quantum_sha520.py       # Reversible circuits

│   └── grover_sha520.py        # Grover's algorithm

└── simulators/

    ├── tn_simulator.py         # Tensor network MPS

    └── qiskit_simulation.py    # Qiskit wrapper

```

## Key Classes

| Class | Module | Purpose |
|-------|--------|---------|
| `SHA520` | classical.sha520_ref | Full SHA-520 hash (configurable rounds) |

| `ToySHA520` | classical.toy_permutations | Reduced-round toy version (4 rounds, 128-bit) |
| `ReversibleSHA520` | quantum.quantum_sha520 | Reversible quantum oracle |

| `GroverSHA520` | quantum.grover_sha520 | Grover's preimage search |
| `QuantumCircuit` | quantum.quantum_sha520 | Device-independent circuit abstraction |

| `TensorNetworkSimulator` | simulators.tn_simulator | MPS quantum simulator |

## Important Constants

- **SHA-520 digest size**: 65 bytes (520 bits)
- **SHA-520 block size**: 128 bytes (1024 bits)
- **Toy SHA-520 digest size**: 16 bytes (128 bits)
- **Grover optimal iterations**: π/4 × √(search space)

## Performance Notes

- **SHA-520-4** (4 rounds): ~10-100x faster than SHA-520-80
- **Toy SHA-520**: ~100x faster than full SHA-520
- **Quantum advantage**: Appears at ~48-bit search space
- **Resource scaling**: Circuit depth ∝ √(search space) for Grover

## Common Use Cases

### Test Quantum Attack Strategy
```python

# Use toy SHA-520 for fast iteration

toy = ToySHA520(rounds=4)

target = toy.digest(b"test_message")



# Estimate Grover resources

from python.quantum import estimate_resources

resources = estimate_resources(rounds=4, target_bits=16)

print(f"Qubits needed: {resources['total_logical_qubits']}")

```

### Analyze Speedup at Different Scales
```python

from python.quantum import grover_speedup_vs_classical



for bits in [16, 32, 48, 64]:

    speedup = grover_speedup_vs_classical(target_bits=bits)

    print(f"{bits}-bit: {speedup['speedup_factor']:.2e}x")

```

### Profile Classical Attack
```python

from python.classical import timing_benchmark



sha = SHA520(rounds=80)

benchmark = timing_benchmark(sha.digest, message_size=128, iterations=1000)

print(f"Throughput: {benchmark['throughput_mbps']:.1f} MB/s")

```

## Optional Dependencies

```bash

# For Qiskit integration

pip install qiskit qiskit-aer



# For better performance

pip install numpy scipy

```

## Reference Documentation

- SHA-520 spec: 520-bit output, configurable rounds
- Grover complexity: O(√N) queries for N-item search
- Physical qubits: ~1000× logical qubits with surface code error correction
- Gate time assumptions: 100 ns (current NISQ baseline)

## Troubleshooting

**ImportError on quantum module**: Check relative imports in `quantum/grover_sha520.py`

**Qiskit warnings**: These are safe; Qiskit is optional. Resource estimates work without it.

**Memory issues on large simulations**: MPS simulator designed for ≤16 qubits; use resource estimates for larger systems.

**Unrealistic speedups**: Remember speedup scales with qubit count and error rates; current NISQ hardware would not achieve these advantages.