wings-quantum 0.1.0__py3-none-any.whl

wings_quantum-0.1.0.dist-info/METADATA

@@ -0,0 +1,491 @@
+Metadata-Version: 2.4
+Name: wings-quantum
+Version: 0.1.0
+Summary: Wavepacket Initialization on Neighboring Grid States - GPU-accelerated variational quantum state preparation
+Author-email: Joshua Courtney <joshuamcourtney@gmail.com>
+Maintainer-email: Your Name <joshuamcourtney@gmail.com>
+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: 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,docs,gpu]; 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 |
+|--------|-------------|------------|----------|-----------------|
+| 4 | 16 | 16 | ~1000s | 1e-10
+| 5 | 32 | 25 | ~1500s | 1e-8 | 
+| 8 | 256 | 64 | ~3000s | 1e-6 |
+
+### 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

wings_quantum-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+wings/__init__.py,sha256=pLICaGXkT5YrxfYcZs2dQE4BtScJtbI1a4PmKSdHulk,7191
+wings/adam.py,sha256=Yru4S66l6uCoWBiQh2GjHLW7eDrV4HMgOqVBo-9X0GA,4128
+wings/ansatz.py,sha256=292RM_vkt28SZvqXHRAwANZgd8URroSPtK7eGQUsXhY,6705
+wings/benchmarks.py,sha256=DdKYiK17xFBRPu98sDuPztoe3NREUP2Qo9P9sWmEzrI,17506
+wings/campaign.py,sha256=J6EJ2UDq42bmzAhrhKPw9d9dozL8-HizCIjBHJawYS0,24018
+wings/cli.py,sha256=mQBlvXSZkNTHHcaFuquLtsZqqyswxJjKPbvHvpV4o3Y,10393
+wings/compat.py,sha256=WGNiSDNjSBoKQ1FSfVEyTEfF43z3_g43zhRhjTN7tTs,3882
+wings/config.py,sha256=-LQbNcNHncubgp5AGfi750IPI6x5linGCqt1wZjNjUc,14523
+wings/convenience.py,sha256=vxRATMv9yIN9rsvQIw2vNY31rrlAEtDAk1UxLbUWTMU,8150
+wings/export.py,sha256=lihJ6lS9zKBUj9jwCXPnUXyQmAI8FUkpVaDqCWKDilA,6579
+wings/optimizer.py,sha256=mDdmVPlerIS4BAPPWvF4O6s68RF-6hk-u_hm3tuhc1Q,76698
+wings/paths.py,sha256=Pu2SSuWjiZwE09wFPSx0WMMnwToS5JqK3JWgqaLLUvk,10032
+wings/py.typed,sha256=Y3QpSe9qtWcL1vKplcWdRY0cn5071TLJQWBO0QbxTm8,84
+wings/results.py,sha256=pvfQw7WVSTXTuPQ_Ne9ktpg8XLcmvYM8to9yTR7gdq8,9524
+wings/types.py,sha256=T57MVbbA_0k1bKSNS6dMu8CnrIvweLBf22lUQux7Oa0,292
+wings/evaluators/__init__.py,sha256=kQYb2GE0CCFxk00Rl5eqE6IUHwkT4oKpyK4W35Kpdh0,482
+wings/evaluators/cpu.py,sha256=zOIhpTyeVl3l3GO-812spPrC9Iab5y8dnLOIvlrNCPg,2707
+wings/evaluators/custatevec.py,sha256=lL_OwZN6jdKx_9UkcCW86ux_Z1Pl8Hpw5VwfpXihlgg,27425
+wings/evaluators/gpu.py,sha256=AzaA5dVJVkLum4LCHH_15yhYNYjXvDiF_dfbYqe-ql8,7527
+wings_quantum-0.1.0.dist-info/licenses/LICENSE.txt,sha256=omczQTVMzXdIpw4Zqea8K6lKnZGV0sKOUiv0goFaxGk,1075
+wings_quantum-0.1.0.dist-info/METADATA,sha256=0LmAgCvJ0lAZJd9h5v-2wqQwtDxyzGZ40bbA3tkOLuU,15369
+wings_quantum-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+wings_quantum-0.1.0.dist-info/entry_points.txt,sha256=EyDWtAiTb_FrlYRjg7iVofIJDBjKxQ1yC8-DDrrlP-Q,41
+wings_quantum-0.1.0.dist-info/top_level.txt,sha256=BL_U5mIGslHqe_fn24qeBxF-Y5PoirlCh49eOhd6Joo,6
+wings_quantum-0.1.0.dist-info/RECORD,,

wings_quantum-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wings_quantum-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wings = wings.cli:main

wings_quantum-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+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.

wings_quantum-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wings