holopy 0.1.0
Holographic Universe Simulation Framework
Requires Python: >=3.8

# HoloPy: Holographic Universe Simulation Framework
## Overview
HoloPy is a high-performance quantum simulation framework implementing dual-continuum evolution with holographic principles. The framework enables researchers to study quantum-classical coupling through numerical simulation while maintaining holographic bounds and information conservation laws.
## Installation
### System Requirements
* Python 3.8 or higher
* 16GB RAM minimum (32GB recommended)
* CUDA-capable GPU recommended for large simulations
* Linux/Unix environment recommended (Windows supported with limitations)
### Dependencies
* NumPy >= 1.20.0
* SciPy >= 1.7.0
* Pandas >= 1.3.0
* h5py >= 3.0.0
* matplotlib >= 3.4.0 (optional, for visualization)
* numba >= 0.54.0 (optional, for performance optimization)
* pytest >= 6.0.0 (for running tests)
### Installation Steps
1. Create and activate a virtual environment:
```bash
python -m venv holopy-env
source holopy-env/bin/activate
# or
.\holopy-env\Scripts\activate   # Windows
```
2. Install required dependencies:
```bash
pip install -r requirements.txt
```
3. Install optional dependencies:
```bash
pip install -r requirements/dev.txt    # Development tools
pip install -r requirements/test.txt   # Testing framework
pip install -r requirements/docs.txt   # Documentation tools
```
4. Install HoloPy in development mode:
```bash
pip install -e .[dev]
```

Core Features
1. Quantum State Evolution
    * Dual continuum quantum state propagation
    * Holographic principle enforcement
    * Information generation rate modeling (γ ≈ 1.89 × 10⁻²⁹ s⁻¹)
    * Cross-continuum coupling mechanics
    * Active inference implementation

2. Performance Optimization
    * Advanced LRU caching system
    * Numba-accelerated computations
    * Memory-efficient state management
    * GPU acceleration support
    * Parallel evolution capabilities

3. State Management
    * Automated checkpointing
    * State persistence and recovery
    * Validation suite
    * Error correction
    * Version-controlled state storage

4. Metrics Collection
    * Real-time performance monitoring
    * Physics validation metrics
    * Cache efficiency tracking
    * Memory usage statistics
    * Computation time profiling
## Usage Guide
### Basic Implementation
```python
from holopy.core import HilbertSpace, HilbertContinuum
from holopy.metrics import MetricsCollector

# Initialize simulation space
hilbert = HilbertSpace(
    spatial_points=128,
    spatial_extent=10.0
)

# Create continuum system
continuum = HilbertContinuum(
    hilbert_space=hilbert,
    enable_active_inference=True
)

# Initialize state and metrics
continuum.create_initial_state()
metrics_collector = MetricsCollector()

# Evolution loop
for t in range(1000):
    # Evolve system
    continuum.evolve(dt=0.01)
    
    # Collect and validate metrics
    metrics = metrics_collector.collect(continuum)
    metrics_collector.validate_conservation_laws(metrics)
    
    # Optional: Save checkpoint
    if t % 100 == 0:
        continuum.save_checkpoint(f"checkpoint_{t}")
```
### Advanced Features
#### State Persistence
```python
from holopy.utils import StatePersistence

persistence = StatePersistence(
    base_path="simulations/",
    compression_level=9
)

# Save complete system state
persistence.save_state(
    continuum.state,
    "simulation_1",
    metadata={'timestamp': time.time()}
)

# Load previous state
loaded_state = persistence.load_state(
    "simulation_1",
    validate_checksum=True
)
```
#### Performance Optimization
```python

from holopy.optimization import PerformanceOptimizer

optimizer = PerformanceOptimizer(
    spatial_points=128,
    cache_size=1000,
    enable_gpu=True
)

# Use optimized evolution
evolved_state = optimizer.optimized_evolution_step(
    state.wavefunction,
    propagator,
    dt=0.01
)
```
### Validation and Testing
#### Running Tests
```bash
# Run all tests
pytest tests/

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/performance/

# Run with coverage report
pytest --cov=holopy tests/
```
#### Physics Validation
The framework automatically validates:
* Conservation laws
* Boundary conditions
* Stability measures
* Information bounds
* State normalization
* Holographic principle compliance

### Performance Considerations
* Memory Management
    * States are stored as memory-mapped arrays for large simulations
* Automatic garbage collection of unused states
    * Configurable cache sizes and eviction policies
    * Compressed state storage for checkpoints
* Computation Optimization
    * FFT-based evolution
    * Cached propagator matrices
    * Parallel state evolution
    * GPU acceleration for large systems
    * Optimized numerical operations

### Error Handling and Logging
* Logging Configuration
    * Configured in logging.ini file
```python
import logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```
### Error Recovery
The framework implements automatic error recovery:
* Checkpoint restoration
* State validation
* Error correction
* Exception handling
* Diagnostic logging

Contributing
Development Setup
Fork the repository
Create a feature branch
Install development dependencies
Implement features/fixes
Add tests
Submit pull request
Code Style
Follow PEP 8 guidelines
Add type hints
Include docstrings
Write unit tests
Update documentation
## License and Citation
### MIT License
Copyright (c) 2024 HoloPy Contributors
### Citation
```
@software{holopy2024,
  title={HoloPy: A Quantum Simulation Framework for Holographic Universe Theory},
  author={HoloPy Contributors},
  year={2024},
  url={https://github.com/bryceweiner/holopy}
}
```
### Getting Help
* GitHub Issues: https://github.com/yourusername/holopy/issues
* Documentation: https://holopy.readthedocs.io/

## Acknowledgments
This project builds on theoretical work in holographic universe theory and advances in quantum simulation. Special thanks to the scientific Python community for providing robust tools and libraries that make this work possible.