Metadata-Version: 2.4
Name: vgon
Version: 0.0.5
Summary: Variational Generative Optimization Network (VGON).
Author: Lingxia Zhang, Xiaodie Lin
License: MIT License
        
        Copyright (c) 2025 Lingxia Zhang, Xiaodie Lin
        
        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://vgon.funqitang.cn
Project-URL: Repository, https://github.com/zhangjianjianzz/VGON.git
Project-URL: Documentation, https://vgon.funqitang.cn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cvxpy
Requires-Dist: numpy
Provides-Extra: core
Requires-Dist: torch; extra == "core"
Requires-Dist: toqito>=1.1.2; extra == "core"
Requires-Dist: cvxpy>=1.7.2; extra == "core"
Requires-Dist: cvxpylayers>=0.1.9; extra == "core"
Requires-Dist: pennylane>=0.42.3; extra == "core"
Requires-Dist: pennylane-lightning>=0.42.0; extra == "core"
Provides-Extra: plot
Requires-Dist: pandas>=2.3.2; extra == "plot"
Requires-Dist: ptiprince>=0.2.7; extra == "plot"
Requires-Dist: scipy>=1.16.2; extra == "plot"
Requires-Dist: seaborn>=0.13.2; extra == "plot"
Provides-Extra: notebook
Requires-Dist: ipykernel>=6.30.1; extra == "notebook"
Provides-Extra: doc
Requires-Dist: mkdocs-material; extra == "doc"
Requires-Dist: mkdocs-literate-nav>=0.6.2; extra == "doc"
Requires-Dist: mdx-truly-sane-lists>=1.3; extra == "doc"
Provides-Extra: full
Requires-Dist: vgon[core,doc,notebook,plot]; extra == "full"
Dynamic: license-file

# VGON Environment Setup

VGON scripts here require Python version 3.11 and above.

This guide provides instructions for setting up the VGON (Variational Generative Optimization Network) environment using either `uv` or `pip`.

## Prerequisites

- Python 3.11 or higher
- Git

## Method 1: Using uv (Recommended)

[uv](https://github.com/astral-sh/uv) is a fast Python package manager and project manager, whose installation is simple as [guide](https://docs.astral.sh/uv/#installation)


### Setup with uv
1. Clone the repository to local disk.
    ```bash
    git clone https://github.com/zhangjianjianzz/VGON.git && cd VGON
    ```
2. Create virtual environment if it wasn't contained
    ```bash
    uv venv .venv
    ```
    The python virtual environment will be located at `.venv` fold under root path in default. Linux/macOS users could activate it in shell by typing
    ```bash
    source .venv/bin/activate
    ```
3. Install dependecies in `.venv` for VGON scripts 
    ```bash
    uv sync --extra full
    ```
    `plot` and `notebook` groups are optional for VGON itself. 

4. Running experiments with uv
    ```bash
    # Run specific experiments
    uv run python BP/HXXZ/vgon_xxz.py
    uv run python Gap/Mix.py
    uv run python Degeneracy/H232/H232.py

    # Or activate environment first
    source .venv/bin/activate
    python BP/HXXZ/plot.py
    ```

## Method 2: Using pip

### Setup with pip

```bash
# Clone the repository
git clone <your-repo-url>
cd VGON

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Linux/macOS
# or
venv\Scripts\activate     # On Windows

# Upgrade pip
pip install --upgrade pip

# Install PyTorch (CPU version)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# For GPU support (CUDA 12.1), use instead:
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Install the package with dependencies
pip install -e .

# Install optional dependencies
pip install -e ".[plot]"     # For plotting
pip install -e ".[dev]"      # For development
pip install -e ".[gpu]"      # For GPU acceleration
pip install -e ".[all]"      # Install everything

# Manual installation of ptitprince (if needed)
pip install git+https://github.com/pog87/PtitPrince.git
```

## Verify Installation

Test your installation by running a simple example:

```python
import torch
import pennylane as qml
import numpy as np

# Test basic functionality
print(f"PyTorch version: {torch.__version__}")
print(f"PennyLane version: {qml.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")

# Test quantum device
dev = qml.device("default.qubit", wires=2)
print("✓ PennyLane quantum device created successfully")
```

## Project Structure

```
VGON/
├── BP/              # Barren Plateau experiments
│   ├── HXXZ/        # Heisenberg XXZ model
│   └── Z1Z2/        # Z1Z2 model
├── Degeneracy/      # Degeneracy detection experiments
│   ├── H232/        # H232 Hamiltonian
│   └── MG/          # Graph states
├── Gap/             # Nonlocality gap experiments
└── results/         # Experimental results
```

## Running Experiments

### Barren Plateau Experiments
```bash
# HXXZ model
python BP/HXXZ/vgon_xxz.py    # Run VGON training
python BP/HXXZ/vqe_xxz.py     # Run VQE baseline
python BP/HXXZ/plot.py        # Generate plots

# Z1Z2 model
python BP/Z1Z2/vgon_z1z2.py
python BP/Z1Z2/vqe_z1z2.py
python BP/Z1Z2/plot.py
```

### Degeneracy Detection
```bash
# H232 Hamiltonian
python Degeneracy/H232/H232.py
python Degeneracy/H232/plot.py

# Graph states
python Degeneracy/MG/MG.py
python Degeneracy/MG/plot.py
```

### Nonlocality Gap
```bash
python Gap/Mix.py              # Train gap model
matlab -batch "run('Gap/plotGap.m')"  # Generate MATLAB plots
```

## Troubleshooting

### Common Issues

1. **CUDA not found**: If you have a GPU but CUDA is not detected, reinstall PyTorch with CUDA support
2. **PennyLane device errors**: Ensure you have the correct PennyLane plugins installed
3. **Memory issues**: Reduce batch sizes in the configuration files
4. **Import errors**: Make sure all dependencies are installed correctly

### GPU Setup

For GPU acceleration:


### Development Setup

For contributors:

## Support

- Paper: [Commun Phys 8, 334 (2025)](https://doi.org/10.1038/s42005-025-02261-4)
- Issues: Create an issue on the GitHub repository
- Documentation: See individual module docstrings and comments

# [Development Containers](https://containers.dev/)
DevContainers' configuration in vscode/GitHub Codespace.

