Metadata-Version: 2.4
Name: wings-quantum
Version: 0.4.1
Summary: Wavepacket Initialization on Neighboring Grid States - GPU-accelerated variational quantum state preparation
Author-email: Joshua Courtney <joshuamcourtney@gmail.com>
Maintainer-email: Joshua Courtney <joshuamcourtney@gmail.com>
License: MIT License
        
        Copyright (c) 2026 WINGS Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/jmcourtneyuga/wings
Project-URL: Documentation, https://github.com/jmcourtneyuga/wings
Project-URL: Repository, https://github.com/jmcourtneyuga/wings.git
Project-URL: Issues, https://github.com/jmcourtneyuga/wings/issues
Project-URL: Changelog, https://github.com/jmcourtneyuga/wings/blob/main/CHANGELOG.md
Keywords: quantum computing,variational quantum algorithms,quantum state preparation,gaussian wavefunction,wavepacket,qiskit,cuQuantum,GPU acceleration,VQA,quantum simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Requires-Dist: qiskit>=1.0
Requires-Dist: matplotlib>=3.5
Provides-Extra: gpu
Requires-Dist: qiskit-aer>=0.13; extra == "gpu"
Requires-Dist: cuquantum-python>=23.0; extra == "gpu"
Requires-Dist: cupy-cuda11x>=12.0; extra == "gpu"
Provides-Extra: jax
Requires-Dist: jax>=0.4; extra == "jax"
Requires-Dist: jaxlib>=0.4; extra == "jax"
Provides-Extra: viz
Requires-Dist: plotly>=5.0; extra == "viz"
Provides-Extra: hardware
Requires-Dist: qiskit-ibm-runtime>=0.20; extra == "hardware"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: pylatexenc>=2.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Provides-Extra: all
Requires-Dist: wings-quantum[dev,gpu,hardware,jax,viz]; extra == "all"
Dynamic: license-file

# WINGS: Wavepacket Initialization on Neighboring Grid States

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CUDA](https://img.shields.io/badge/CUDA-11.0+-green.svg)](https://developer.nvidia.com/cuda-toolkit)

**WINGS** is a high-performance, GPU-accelerated variational quantum state preparation toolkit for preparing continuous wavepacket states on discrete qubit grids. 
It enables researchers to achieve machine-precision fidelities (>0.999999999) when 
encoding Gaussian, Lorentzian, and other continuous wavefunctions into quantum circuits.

This degree of precision is not (!) a guarantee, seeing as the optimization landscape is full of barren plateaus and local minima. 
This is another reason why you can perform multiple jobs and batched jobs.

## Documentation

See [DOCUMENTATION.md] for the full API reference and guides.

## Overview

Quantum algorithms for simulating continuous systems—such as molecular dynamics, quantum field theories, and wave propagation—require encoding continuous wavefunctions onto discrete qubit registers. WINGS addresses this challenge by providing:

- **Variational quantum circuits** optimized to prepare target wavepackets with ultra-high fidelity
- **GPU acceleration** via NVIDIA cuStateVec (cuQuantum) for 5–20x speedups over CPU
- **Multi-GPU support** for scaling to larger qubit counts
- **Production-grade tooling** for running thousands of optimization campaigns with automatic checkpointing

## Features

### Target Wavefunctions

- **Gaussian**: Standard Gaussian wavepackets with configurable width (σ) and center (x₀)
- **Lorentzian**: Cauchy distributions for heavy-tailed profiles
- **Hyperbolic Secant**: Soliton-like profiles for nonlinear dynamics
- **Custom Functions**: Any user-defined wavefunction via callback

### Acceleration Backends

| Backend | Description | Speedup |
|---------|-------------|---------|
| CPU | Qiskit Statevector (baseline) | 1x |
| GPU (Aer) | Qiskit Aer with CUDA | 2–5x |
| cuStateVec | NVIDIA cuQuantum direct API | 5–20x |
| Multi-GPU | Parallel cuStateVec across GPUs | Linear scaling |

### Optimization Methods

- **L-BFGS-B**: Quasi-Newton method for high-precision convergence
- **Adam**: Momentum-based optimizer for escaping local minima
- **Basin Hopping**: Global optimization with local refinement
- **Hybrid Pipelines**: Adaptive multi-stage optimization

### Production Features

- Automatic checkpointing and resume for long campaigns
- Parallel campaign execution with configurable strategies
- Comprehensive result aggregation and statistical analysis
- Cross-platform path management for HPC clusters

## Installation

### Prerequisites

- Python 3.9 or higher
- Qiskit 1.0+
- NumPy, SciPy

### Basic Installation

```bash
pip install wings-quantum
```

### With GPU Support

```bash
# Install CUDA toolkit (11.0+) first, then:
pip install wings-quantum[gpu]

# For cuStateVec acceleration (recommended):
pip install cuquantum-python cupy-cuda11x
```

### From Source

```bash
git clone https://github.com/jmcourtneyuga/wings.git
cd wings
pip install -e ".[dev,gpu]"
```

### Verify Installation

```bash
# Check available backends
python -c "from wings import print_backend_info; print_backend_info()"

# Or use the CLI
gso info
```

## Quick Start

### Basic Optimization

```python
from wings import GaussianOptimizer, OptimizerConfig

# Configure the optimization
config = OptimizerConfig(
    n_qubits=8,           # 2^8 = 256 grid points
    sigma=0.5,            # Gaussian width
    use_custatevec=True,  # Enable GPU acceleration
)

# Create optimizer and run
optimizer = GaussianOptimizer(config)
results = optimizer.optimize_ultra_precision(target_infidelity=1e-10)

print(f"Fidelity achieved: {results['fidelity']:.12f}")
print(f"Infidelity (1-F):  {results['infidelity']:.3e}")
```

### High-Level Convenience API

```python
from wings import optimize_gaussian_state

results, optimizer = optimize_gaussian_state(
    n_qubits=10,
    sigma=0.5,
    target_infidelity=1e-11,
    max_time=3600,  # 1 hour
    plot=True,
    save=True,
)
```

### Production Campaign

```python
from wings import run_production_campaign

results = run_production_campaign(
    n_qubits=8,
    sigma=0.5,
    total_runs=1000,
    target_infidelity=1e-11,
)

results.print_summary()
```

### Custom Target Wavefunction

```python
import numpy as np
from wings import OptimizerConfig, GaussianOptimizer, TargetFunction

# Define a double-Gaussian wavepacket
def double_gaussian(x):
    return np.exp(-((x - 1)**2) / 0.5) + np.exp(-((x + 1)**2) / 0.5)

config = OptimizerConfig(
    n_qubits=10,
    target_function=TargetFunction.CUSTOM,
    custom_target_fn=double_gaussian,
    box_size=5.0,
)

optimizer = GaussianOptimizer(config)
results = optimizer.optimize_ultra_precision(target_infidelity=1e-9)
```

### Custom Ansatz

```python
from wings import CustomHardwareEfficientAnsatz, OptimizerConfig, GaussianOptimizer

# Create a custom hardware-efficient ansatz
ansatz = CustomHardwareEfficientAnsatz(
    n_qubits=8,
    layers=6,
    entanglement='circular',  # 'linear', 'circular', or 'full'
    rotation_gates=['ry', 'rz'],
)

config = OptimizerConfig(
    n_qubits=8,
    sigma=0.5,
    ansatz=ansatz,
    use_custatevec=True,
)

optimizer = GaussianOptimizer(config)
results = optimizer.run_optimization()
```

### Exporting Optimized Circuits:

from wings import GaussianOptimizer, OptimizerConfig

# Run optimization
config = OptimizerConfig(n_qubits=8, sigma=0.5)
optimizer = GaussianOptimizer(config)
results = optimizer.optimize_ultra_precision(target_infidelity=1e-10)

# Get the optimized circuit
circuit = optimizer.get_optimized_circuit()
print(circuit.draw())

# Export to OpenQASM 2.0
qasm_str = optimizer.export_qasm()
print(qasm_str)

# Export to OpenQASM 3.0
qasm3_str = optimizer.export_qasm(version=3)

# Save to file (various formats)
optimizer.save_circuit("gaussian_prep.qasm")          # OpenQASM 2.0
optimizer.save_circuit("gaussian_prep.qasm3", format='qasm3')  # OpenQASM 3.0
optimizer.save_circuit("gaussian_prep.qpy", format='qpy')      # Qiskit QPY
optimizer.save_circuit("gaussian_prep.png", format='png')      # Circuit diagram

## Command-Line Interface

WINGS includes a full CLI for common tasks:

```bash
# Run optimization
gso optimize --qubits 8 --sigma 0.5 --target-infidelity 1e-10

# Run production campaign
gso campaign --qubits 8 --sigma 0.5 --runs 1000 --resume

# Benchmark GPU performance
gso benchmark --qubits 12

# Find GPU crossover point
gso crossover --min-qubits 6 --max-qubits 18

# Show backend information
gso info

# List/load campaigns
gso campaigns list
gso campaigns load campaign_q8_s0.50_20250203_120000
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GSO_BASE_DIR` | Base directory for all data | `~/.wings` |
| `GSO_CACHE_DIR` | Coefficient cache directory | `$GSO_BASE_DIR/cache` |
| `GSO_OUTPUT_DIR` | Simulation outputs | `$GSO_BASE_DIR/output` |
| `GSO_CHECKPOINT_DIR` | Optimization checkpoints | `$GSO_BASE_DIR/checkpoints` |
| `GSO_CAMPAIGN_DIR` | Campaign results | `$GSO_BASE_DIR/campaigns` |

### HPC Cluster Support

WINGS automatically detects common HPC scratch directories:

- `/scratch/$USER` (SLURM)
- `/work/$USER` (PBS/Torque)
- `/gpfs/scratch/$USER` (GPFS)
- `/lustre/scratch/$USER` (Lustre)
- `$SCRATCH` and `$WORK` environment variables

## Project Structure

```
wings/
├── src/
│   └── wings/
│       ├── __init__.py          # Public API and lazy imports
│       ├── py.typed             # PEP 561 marker
│       ├── optimizer.py         # Core GaussianOptimizer class
│       ├── config.py            # Configuration dataclasses
│       ├── ansatz.py            # Quantum circuit ansatz implementations
│       ├── campaign.py          # Large-scale campaign management
│       ├── results.py           # Result tracking and analysis
│       ├── adam.py              # Adam optimizer implementation
│       ├── convenience.py       # High-level convenience functions
│       ├── cli.py               # Command-line interface
│       ├── benchmarks.py        # Performance benchmarking
│       ├── paths.py             # Cross-platform path management
│       ├── compat.py            # cuQuantum compatibility layer
│       ├── types.py             # Type aliases
│       └── evaluators/
│           ├── __init__.py
│           ├── cpu.py           # Thread-safe CPU evaluator
│           ├── gpu.py           # Qiskit Aer GPU evaluator
│           └── custatevec.py    # NVIDIA cuStateVec evaluator
├── tests/
│   ├── conftest.py              # Shared fixtures
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── docs/                        # Sphinx documentation
├── examples/                    # Example notebooks and scripts
├── pyproject.toml
├── Makefile
├── README.md
├── DOCUMENTATION.md
├── CHANGELOG.md
└── LICENSE
```

## Performance

### Typical Results

| Qubits | Grid Points | Parameters | GPU Time | Best Infidelity |
|--------|-------------|------------|----------|-----------------|
| 8 | 256 | 64 | ~30s | 1e-12 |
| 10 | 1,024 | 100 | ~2min | 1e-11 |
| 12 | 4,096 | 144 | ~10min | 1e-10 |
| 14 | 16,384 | 196 | ~1hr | 1e-9 |

### Benchmarking

```python
from wings import benchmark_gpu, find_gpu_crossover

# Benchmark specific configuration
result = benchmark_gpu(n_qubits=12, sigma=0.5)
print(f"GPU speedup: {result.results['custatevec']['speedup_vs_cpu']:.1f}x")

# Find crossover point where GPU becomes faster
crossover = find_gpu_crossover(qubit_range=range(6, 18, 2))
```

## API Reference

### Core Classes

- **`GaussianOptimizer`**: Main optimizer class with all optimization methods
- **`OptimizerConfig`**: Configuration for single optimizations
- **`CampaignConfig`**: Configuration for large-scale campaigns
- **`CampaignResults`**: Aggregated results from campaigns
- **`OptimizationPipeline`**: Multi-stage optimization configuration

### Ansatz Classes

- **`DefaultAnsatz`**: Standard hardware-efficient ansatz with RY rotations and linear CNOT entanglement
- **`CustomHardwareEfficientAnsatz`**: Configurable ansatz with multiple entanglement patterns
- **`AnsatzProtocol`**: Protocol for implementing custom ansatze

### Evaluators

- **`ThreadSafeCircuitEvaluator`**: CPU-based thread-safe evaluator
- **`GPUCircuitEvaluator`**: Qiskit Aer GPU evaluator
- **`CuStateVecEvaluator`**: Single-GPU cuStateVec evaluator
- **`BatchedCuStateVecEvaluator`**: Batched GPU evaluation
- **`MultiGPUBatchEvaluator`**: Multi-GPU parallel evaluator

### Convenience Functions

- **`optimize_gaussian_state()`**: High-level optimization with sensible defaults
- **`quick_optimize()`**: Fast optimization for testing
- **`run_production_campaign()`**: Launch large-scale campaigns
- **`load_campaign_results()`**: Load saved campaign results
- **`list_campaigns()`**: List available campaigns

### Exporting

- **`build_optimized_circuit()`**: Build a QuantumCircuit with bound parameters
- **`export_to_qasm()`**: Export to OpenQASM 2.0 string
- **`export_to_qasm3()`**: Export to OpenQASM 3.0 string  
- **`save_circuit()`**: Save circuit to file (QASM, QPY, PNG, SVG, PDF)


## Development

### Setup

```bash
git clone https://github.com/jmcourtneyuga/wings.git
cd wings
pip install -e ".[dev]"
```

### Running Tests

```bash
# Fast unit tests
make test

# All tests including integration
make test-all

# With coverage
make coverage
```

### Code Quality

```bash
# Format and lint
make format
make lint

# Full check (format + lint + test)
make check
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Citation

If you use WINGS in your research, please cite:

```bibtex
@software{wings2026,
  title={WINGS: Wavepacket Initialization on Neighboring Grid States},
  author={Joshua Courtney},
  year={2026},
  url={https://github.com/jmcourtneyuga/wings}
}
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Qiskit](https://qiskit.org/) for the quantum circuit framework
- [NVIDIA cuQuantum](https://developer.nvidia.com/cuquantum-sdk) for GPU acceleration
- [CuPy](https://cupy.dev/) for GPU array operations

## See Also

- [Full Documentation](DOCUMENTATION.md) - Detailed API documentation and guides
- [Examples](examples/) - Jupyter notebooks and scripts
