README.md

---
license: agpl-3.0
library_name: pytorch
pipeline_tag: other
tags:
- experimental
- research
- associative-memory
- wave-interference
- memory-systems
- tensor-operations
- pytorch
language:
- en
datasets:
- custom
model_type: associative-memory
widget:
- text: "Pattern storage and retrieval demonstration"
  example_title: "Basic Memory Test"
- text: "Wave interference pattern analysis"
  example_title: "Interference Analysis"
inference:
  parameters:
    L: 64
    H: 32
    W: 32
    K: 8
    codes: hadamard
model-index:
- name: WrinkleBrane
  results: []
---

# WrinkleBrane - Experimental Wave-Interference Memory

<div align="center">

**⚠️ Research Prototype ⚠️**

*Early-stage experimental system requiring significant validation*

![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)
![Status](https://img.shields.io/badge/Status-Research%20Prototype-yellow.svg)
![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-red.svg)

</div>

## Model Description

WrinkleBrane is a novel experimental approach to associative memory that uses wave-interference patterns in tensor operations. The system stores information in stacked 2D "membranes" and retrieves it through parallel vertical slicing operations, demonstrating promising initial results on controlled test cases.

**This is a research prototype with significant limitations and is not ready for production use.**

### Model Details

- **Model Type**: Experimental associative memory system
- **Architecture**: Wave-interference tensor operations with orthogonal code spaces
- **Framework**: PyTorch
- **License**: AGPL-3.0
- **Research Status**: Early experimental phase requiring extensive validation

### Key Innovation

- **Wave-interference memory**: Novel tensor-based approach using constructive/destructive interference patterns
- **Orthogonal code spaces**: Hadamard and DCT codes for minimal cross-talk
- **Parallel retrieval**: Single-pass access to all stored patterns via tensor slicing
- **Mathematical foundation**: Theoretically grounded in linear algebra and signal processing

## Intended Uses

### Research Applications ✅

- **Academic research** in associative memory systems
- **Algorithm development** and interference pattern studies  
- **Proof-of-concept** demonstrations for wave-based memory
- **Educational purposes** for understanding tensor interference

### Not Suitable For ❌

- **Production applications** (requires extensive validation)
- **Large-scale deployment** (scalability unproven)
- **Mission-critical systems** (reliability not established)
- **Commercial use** without significant additional development

## Performance and Limitations

### Demonstrated Capabilities

- **High precision**: 150+ dB PSNR on simple geometric test patterns
- **Theoretical consistency**: Behavior matches mathematical predictions
- **Orthogonal performance**: Excellent results with Hadamard codes (zero cross-correlation)
- **Modular design**: Clean, well-structured PyTorch implementation

### Critical Limitations

- **Limited testing**: Only validated on simple synthetic patterns
- **No baselines**: No comparison to standard associative memory approaches
- **Scale uncertainty**: Performance at practical scales unknown
- **Dataset restriction**: Not tested on realistic, complex data

### Known Issues

- Testing limited to controlled laboratory conditions
- Theoretical capacity limits unconfirmed on real-world data
- No robustness analysis under noise or interference
- Long-term stability and persistence mechanisms underdeveloped

## Technical Specifications

### Core Operations

```python
# Write Operation: Store pattern with interference
M += Σᵢ αᵢ · C[:, kᵢ] ⊗ Vᵢ

# Read Operation: Parallel retrieval via tensor slicing  
Y = ReLU(einsum('blhw,lk->bkhw', M, C) + b)
```

### Tensor Shapes

- **Membranes**: `M ∈ ℝ[B, L, H, W]` - 4D tensor storage
- **Codes**: `C ∈ ℝ[L, K]` - Orthogonal slice weights  
- **Patterns**: `V ∈ ℝ[H, W]` - 2D information maps
- **Output**: `Y ∈ ℝ[B, K, H, W]` - Retrieved patterns

### Requirements

- PyTorch 2.0+
- NumPy
- SciPy (for code generation)
- Matplotlib (for visualization)

## Getting Started

### Installation

```bash
git clone https://huggingface.co/WCNegentropy/WrinkleBrane
cd WrinkleBrane
pip install -r requirements.txt
```

### Basic Usage

```python
from wrinklebrane.membrane_bank import MembraneBank
from wrinklebrane.codes import hadamard_codes
from wrinklebrane.write_ops import store_pairs
from wrinklebrane.slicer import make_slicer

# Setup memory system
B, L, H, W, K = 1, 64, 32, 32, 8
bank = MembraneBank(L=L, H=H, W=W)
bank.allocate(B)

# Generate orthogonal codes
C = hadamard_codes(L, K)
slicer = make_slicer(C)

# Store patterns
keys = [0, 1, 2]  
values = [pattern1, pattern2, pattern3]  # H×W tensors
alphas = [1.0, 1.0, 1.0]

store_pairs(bank.M, C, keys, values, alphas)

# Retrieve all patterns
retrieved = slicer(bank.M[0])  # Shape: [K, H, W]
```

### Running Experiments

```bash
# Basic associative memory test
python experiments/p0_assoc_mem.py --L 64 --H 32 --W 32 --K 8 --codes hadamard

# Performance benchmarking
python performance_benchmark.py

# Comprehensive testing
python comprehensive_test.py
```

## Research Status and Validation Needs

### Current Research Phase

WrinkleBrane is in **early experimental development**. While demonstrating promising technical concepts, extensive validation is required before practical applications.

### Required Validation Work

**High Priority**:
- Systematic comparison to established associative memory baselines
- Evaluation on realistic datasets (MNIST, CIFAR, natural images)
- Statistical analysis with multiple runs and confidence intervals
- Large-scale performance and robustness studies

**Medium Priority**:
- Noise robustness characterization
- Failure mode analysis and system limitations
- Computational efficiency benchmarking vs alternatives
- Long-term stability and persistence validation

### Honest Assessment

**What WrinkleBrane Demonstrates**:
- ✅ Novel tensor-based interference memory approach
- ✅ High precision on controlled test patterns
- ✅ Mathematical consistency with theoretical predictions
- ✅ Clean, modular implementation with test coverage

**What Remains Unproven**:
- ❓ Performance on realistic, complex datasets
- ❓ Competitive advantages over existing approaches  
- ❓ Scalability to practically relevant problem sizes
- ❓ Robustness under real-world conditions

## Citation

If you use WrinkleBrane in your research, please cite:

```bibtex
@software{wrinklebrane2025,
  title={WrinkleBrane: Experimental Wave-Interference Memory},
  author={WCNEGENTROPY HOLDINGS LLC},
  year={2025},
  url={https://huggingface.co/WCNegentropy/WrinkleBrane},
  note={Research prototype - experimental software}
}
```

## Documentation

- 📋 **[Research Status](RESEARCH_STATUS.md)** - Current limitations and validation needs
- 🔬 **[Assessment Report](WRINKLEBRANE_ASSESSMENT.md)** - Experimental results and analysis  
- ⚡ **[Optimization Analysis](OPTIMIZATION_ANALYSIS.md)** - Performance characteristics
- 🛠️ **[Development Workflow](AGENTS.md)** - Testing and development procedures

## License and Disclaimer

This software is released under the AGPL-3.0 license. 

**EXPERIMENTAL SOFTWARE DISCLAIMER**: WrinkleBrane is experimental research software. It has not been validated for production use and may contain bugs, limitations, or unexpected behaviors. Use at your own risk and conduct thorough testing before any practical applications.

## Contributing

We welcome contributions to help validate and improve WrinkleBrane:

- **Research validation**: Comparative studies and benchmarking
- **Testing**: Evaluation on new datasets and use cases
- **Optimization**: Performance improvements and scaling studies
- **Documentation**: Improved explanations and tutorials

Please see our research status document for priority validation needs.

---

*WrinkleBrane represents early-stage research in wave-interference memory systems. While showing promise, it requires substantial additional validation before practical applications.*