Metadata-Version: 2.4
Name: quantumgridos
Version: 0.1.8
Summary: Real-time quantum computing interface for power systems optimization
Home-page: https://github.com/saralsystems/quantumgridos
Author: Saral Systems
Author-email: Saral Systems <contact@saralsystems.com>
Maintainer-email: Saral Systems <contact@saralsystems.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/saralsystems/quantumgridos
Project-URL: Documentation, https://quantumgridos.readthedocs.io
Project-URL: Repository, https://github.com/saralsystems/quantumgridos
Project-URL: Bug Tracker, https://github.com/saralsystems/quantumgridos/issues
Keywords: quantum computing,power systems,optimization,qaoa,vqe,quantum algorithms,grid computing,real-time systems
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: System :: Distributed Computing
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9, <3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit>=0.43.0
Requires-Dist: qiskit-aer>=0.12.0
Requires-Dist: qiskit-optimization>=0.5.0
Requires-Dist: qiskit-algorithms>=0.2.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: pandapower>=2.10.0
Requires-Dist: asyncio-mqtt>=0.12.0
Requires-Dist: aiofiles>=0.8.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: protobuf>=3.19.0
Requires-Dist: structlog>=21.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: sphinx>=4.5.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
Requires-Dist: plotly>=5.0.0; extra == "visualization"
Requires-Dist: seaborn>=0.11.0; extra == "visualization"
Provides-Extra: hardware
Requires-Dist: qiskit-ibm-runtime>=0.14.0; extra == "hardware"
Requires-Dist: pyquil>=3.0.0; extra == "hardware"
Requires-Dist: amazon-braket-sdk>=1.35.0; extra == "hardware"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# QuantumGridOS

[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-latest-orange)](https://saralsystems.github.io/quantumgridos/)

**QuantumGridOS** is a Python library for connecting power systems data to quantum computers.
> [!IMPORTANT]
> This library currently supports Python 3.8 to 3.11. Python 3.12+ is not yet supported.

It enables solving power system optimization problems using quantum algorithms (QAOA, VQE) with minimal latency TCP/IP data exchange.

## 🚀 Features

- **Real-time TCP/IP streaming** for power systems data exchange
- **Quantum algorithm support**: QAOA, VQE, Grover's
- **Power system optimizations**: Unit commitment, MaxCut, OPF, State estimation
- **Low-latency architecture** with async I/O and buffer management
- **Hardware agnostic**: Works with IBM Quantum, IonQ, Rigetti, simulators
- **Extensive examples** and documentation

## 📦 Installation

```bash
pip install quantumgridos
```

For development:
```bash
git clone https://github.com/saralsystems/quantumgridos.git
cd quantumgridos
pip install -e .[dev]
```

## 🎯 Quick Start

### Basic MaxCut for Power Network Partitioning

```python
import quantumgridos as qgo

# Initialize quantum-power interface
interface = qgo.QuantumPowerInterface(
    quantum_backend='qiskit_aer',
    tcp_host='localhost',
    tcp_port=5000
)

# Define power network
network = qgo.PowerNetwork.from_ieee_case(14)  # IEEE 14-bus

# Create MaxCut optimizer for network partitioning
optimizer = qgo.MaxCutOptimizer(
    network=network,
    algorithm='qaoa',
    layers=3
)

# Start real-time processing
async def process_stream():
    async for data in interface.tcp_stream():
        # Solve partitioning problem
        result = await optimizer.solve_async(data)
        
        # Send result back to power system
        await interface.send_result(result)

# Run
import asyncio
asyncio.run(process_stream())
```

### Unit Commitment Example

```python
import quantumgridos as qgo

# Configure unit commitment problem
uc_problem = qgo.UnitCommitment(
    generators=[
        {'name': 'G1', 'pmin': 50, 'pmax': 200, 'cost': 1000},
        {'name': 'G2', 'pmin': 20, 'pmax': 100, 'cost': 1500}
    ],
    demand_forecast=[150, 180, 200, 170],
    time_periods=4
)

# Setup quantum solver
solver = qgo.QuantumSolver(
    problem=uc_problem,
    backend='ibmq_qasm_simulator',
    algorithm='vqe',
    optimizer='cobyla'
)

# Solve with TCP streaming
with qgo.TCPInterface(port=5000) as tcp:
    for demand_update in tcp.stream():
        uc_problem.update_demand(demand_update)
        solution = solver.solve()
        tcp.send(solution.to_scada_format())
```

## 🏗️ Architecture

```
QuantumGridOS/
├── Core Modules
│   ├── quantum_interface.py     # Quantum backend abstraction
│   ├── tcp_handler.py          # High-performance TCP/IP
│   ├── data_encoder.py         # Power data → Qubits
│   └── time_sync.py            # Clock synchronization
├── Algorithms
│   ├── qaoa.py                 # QAOA implementation
│   ├── vqe.py                  # VQE implementation
│   └── grover.py               # Grover's algorithm
├── Power Systems
│   ├── network.py              # Power network modeling
│   ├── optimizations/
│   │   ├── unit_commitment.py
│   │   ├── opf.py             # Optimal Power Flow
│   │   ├── state_estimation.py
│   │   └── maxcut.py
│   └── converters.py           # IEEE/MATPOWER formats
└── Utils
    ├── benchmarks.py
    └── visualization.py
```

## 📊 Benchmarks

| Problem Type | Network Size | Classical (ms) | Quantum (ms) | Speedup |
|-------------|-------------|---------------|--------------|---------|
| MaxCut | IEEE 14-bus | 120 | 45 | 2.67x |
| Unit Commitment | 10 units | 340 | 180 | 1.89x |
| State Estimation | 30-bus | 250 | 110 | 2.27x |

## 🔌 TCP/IP Protocol

QuantumGridOS uses optimized binary protocol for minimal latency:

```python
# Message format
{
    'timestamp': int64,          # Unix timestamp in microseconds
    'msg_type': uint8,          # 0: data, 1: control, 2: result
    'data': {
        'bus_voltages': float32[],
        'line_flows': float32[],
        'generator_status': bool[]
    }
}
```

## 📚 Documentation

Full documentation available at [saralsystems.github.io/quantumgridos](https://saralsystems.github.io/quantumgridos/)

- [Getting Started Guide](https://saralsystems.github.io/quantumgridos/installation.html)
- [Quick Start](https://saralsystems.github.io/quantumgridos/quickstart.html)
- [API Reference](https://saralsystems.github.io/quantumgridos/api/core.html)
- [User Guide](https://saralsystems.github.io/quantumgridos/user_guide/index.html)
- [Tutorials](https://saralsystems.github.io/quantumgridos/tutorials/index.html)

## 🧪 Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest --cov=quantumgridos tests/

# Run benchmarks
python -m quantumgridos.benchmark
```

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

All contributors must sign a Contributor License Agreement (CLA) before their contributions can be merged. See [CLA.md](CLA.md) for individual contributors and [CLA-CORPORATE.md](CLA-CORPORATE.md) for corporate contributors.

## 📄 License

Apache License 2.0 - see [LICENSE](LICENSE) file.

## 📖 Citation

If you use QuantumGridOS in research, please cite:

```bibtex
@software{quantumgridos,
  title = {QuantumGridOS: Real-time Quantum-Power Systems Interface},
  author = {Saral Systems},
  year = {2025},
  url = {https://github.com/saralsystems/quantumgridos},
  license = {Apache-2.0}
}
```

## 🙏 Acknowledgments

Based on research from NREL ARIES and quantum-in-loop (QIL) architecture.
