```markdown
# Quantum Walks

A comprehensive Python package for simulating quantum walks in various dimensions and on complex networks.

## Features

- **Multi-dimensional quantum walks**: 1D, 2D, and 3D discrete-time quantum walks
- **Graph-based quantum walks**: Quantum walks on arbitrary graphs using various coin operators
- **Szegedy quantum walks**: Advanced quantum walks for complex network analysis
- **Quantum ranking algorithms**: Quantum PageRank and node ranking for network analysis
- **Comprehensive visualization**: Built-in plotting utilities for all walk types
- **Performance analysis**: Convergence analysis and comparison tools

## Installation

```bash
pip install quantumwalks
```

## Quick Start

```python
import numpy as np
import networkx as nx
from quantumwalks import DTQW1D, GraphDTQW, QuantumPageRank

# 1D quantum walk
qw1d = DTQW1D(N=100, coin_type='hadamard')
qw1d.initialize_state(init_pos=0)
qw1d.evolve(50)
qw1d.plot()

# Graph quantum walk
graph = nx.karate_club_graph()
gqw = GraphDTQW(graph, coin_type='grover', initial_node=0)
gqw.evolve(10)
gqw.plot()

# Quantum PageRank
qpr = QuantumPageRank(graph)
ranking = qpr.get_ranking()
qpr.plot(plot_type='bar')
```

## Documentation

Full documentation is available at [quantumwalks.readthedocs.io](https://quantumwalks.readthedocs.io)

## Examples

Check the `examples/` directory for comprehensive usage examples:

- `basic_usage.py`: Basic quantum walk simulations
- `network_analysis.py`: Network analysis with quantum walks
- `visualization_demo.py`: Advanced visualization techniques

### Basic 1D Walk Example

```python
from quantumwalks import DTQW1D
import numpy as np

# Initialize 1D quantum walk
qw = DTQW1D(N=100, coin_type='hadamard')
qw.initialize_state(init_pos=0, init_coin=np.array([1, 1j])/np.sqrt(2))

# Evolve and plot
qw.evolve(100)
qw.plot()
```

### Network Analysis Example

```python
import networkx as nx
from quantumwalks import GraphDTQW, QuantumPageRank

# Create complex network
graph = nx.connected_watts_strogatz_graph(20, 4, 0.3)

# Quantum walk on graph
gqw = GraphDTQW(graph, coin_type='grover', initial_node=0)
gqw.evolve(10)
gqw.plot()

# Quantum PageRank analysis
qpr = QuantumPageRank(graph)
ranking = qpr.get_sorted_ranking()
print("Top nodes:", ranking[:5])
```

## Supported Quantum Walk Types

### Discrete-Time Quantum Walks
- **1D Walks**: Line graphs with various coin operators
- **2D Walks**: Lattice graphs with 4-direction movement
- **3D Walks**: Cubic lattices with 6-direction movement

### Graph-Based Walks
- **GraphDTQW**: Quantum walks on arbitrary graphs
- **SzegedyQW**: Szegedy quantum walks for complex networks
- **DTQWPageRank**: Discrete-time quantum walk for node ranking
- **QuantumPageRank**: Quantum PageRank using Szegedy formalism

### Coin Operators
- Hadamard coin
- Grover coin  
- Fourier coin
- SU(n) coin

## Advanced Usage

### Convergence Analysis
```python
from quantumwalks import analyze_convergence, plot_convergence_analysis

graph = nx.barabasi_albert_graph(30, 2)
gqw = GraphDTQW(graph, coin_type='grover', initial_node=0)

# Analyze convergence behavior
convergence_data = analyze_convergence(gqw, max_steps=50)
plot_convergence_analysis(convergence_data)
```

### Quantum vs Classical Comparison
```python
from quantumwalks import compare_classical_quantum

graph = nx.connected_caveman_graph(3, 8)
comparison = compare_classical_quantum(graph)

print(f"Correlation: {comparison['correlation']:.4f}")
print(f"KL Divergence: {comparison['kl_divergence']:.4f}")
```

## API Overview

### Core Classes
- `DTQW1D`, `DTQW2D`, `DTQW3D`: Multi-dimensional quantum walks
- `GraphDTQW`: Quantum walks on arbitrary graphs
- `SzegedyQW`: Szegedy quantum walks
- `DTQWPageRank`, `QuantumPageRank`: Quantum ranking algorithms

### Key Methods
- `evolve(num_steps)`: Evolve quantum walk for specified steps
- `get_probabilities()`: Get current probability distribution
- `plot()`: Visualize results
- `get_ranking()`: Compute node ranking scores

## Dependencies

- Python >= 3.8
- NumPy >= 1.21.0
- SciPy >= 1.7.0
- Matplotlib >= 3.5.0
- NetworkX >= 2.6.0

## Development

To contribute to this project:

```bash
# Clone repository
git clone https://github.com/TDSKS-123/quantumwalks
cd quantumwalks

# Install in development mode
pip install -e .

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

# Run tests
pytest tests/
```

## Citation

If you use this package in your research, please cite:

```bibtex
@software{quantumwalks2025,
  title = {Quantum Walks: A Python package for quantum walk simulations},
  author = {LiangWen},
  year = {2025},
  url = {https://github.com/TDSKS-123/quantumwalks}
}
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Support

If you encounter any problems or have questions:

- Open an issue on [GitHub](https://github.com/TDSKS-123/quantumwalks/issues)
- Check the [documentation](https://quantumwalks.readthedocs.io)

## Changelog

### Version 1.0.0
- Initial release with comprehensive quantum walk implementations
- Support for 1D, 2D, and 3D quantum walks
- Graph-based quantum walks and ranking algorithms
- Advanced visualization and analysis tools