Complex XOR Explorer

An interactive mathematical exploration tool for studying XOR operations on Gaussian integers represented in base (-1+i) notation, creating fascinating geometric patterns and non-linear transformations in the complex plane.

🔬 Mathematical Foundation

This project emerged from investigating the PCG (Permuted Congruential Generator) algorithm and its use of XOR operations for pseudorandom number generation. The exploration led to a fascinating question: What would XOR operations look like when applied to complex numbers?

Key Mathematical Concepts

• Gaussian Integers: Complex numbers with integer real and imaginary parts (e.g., 2+3i, -1+4i)
• Base (-1+i) Representation: A unique number system where any Gaussian integer can be represented using only binary digits (0 and 1)
• Complex XOR Operations: Bitwise XOR applied to the base (-1+i) representations, creating non-linear transformations in the complex plane

Theoretical Background

The base (-1+i) system uses powers of (-1+i) as place values:

• (-1+i)^0 = 1
• (-1+i)^1 = -1+i
• (-1+i)^2 = -2i
• (-1+i)^3 = 2+2i
• etc.

This creates a spiral pattern in the complex plane, and XOR operations on these representations produce unexpected geometric relationships that bridge number theory, complex analysis, and pseudorandom number generation.

🎯 Project Features

Interactive Visualization

• Real-time manipulation of Gaussian integer inputs via sliders
• Multi-panel display showing inputs, results, and mathematical representations
• Trail tracking to visualize transformation patterns over time
• Vector field visualization showing XOR transformation effects
• Binary representation display in base (-1+i) notation

Mathematical Tools

• Type-safe Gaussian integer arithmetic with validation
• Efficient base (-1+i) conversion using greedy algorithms
• XOR operations in complex space with configurable precision
• Power spiral visualization of base (-1+i) place values

Interactive Controls

• Integer-constrained sliders for precise Gaussian integer input
• Preset patterns for exploring specific mathematical configurations
• Auto-rotation animation for continuous pattern observation
• Display toggles for customizing visualization components

🏗️ Architecture

The project follows a clean modular architecture with clear separation of concerns:

complex-xor/
├── src/complex_xor/
│   ├── __init__.py          # Package interface and exports
│   ├── math.py             # Core mathematical types and algorithms
│   └── gui.py              # Visualization and user interface
├── main.py                 # Application entry point
├── docs/
│   └── PROJECT_JOURNAL.md  # Development history and context
└── pyproject.toml          # Project configuration and dependencies

Module Responsibilities

• math.py: Implements GaussianInteger type system and ComplexBinarySystem for base (-1+i) operations
• gui.py: Provides InteractiveComplexXORExplorer with matplotlib-based visualization
• main.py: Simple entry point that launches the GUI application

🚀 Installation and Usage

Prerequisites

• Python 3.13+
• uv package manager

Quick Start

# Clone the repository
git clone <repository-url>
cd complex-xor

# Install dependencies (uv handles virtual environment automatically)
uv sync

# Run the interactive explorer
uv run main.py

Dependencies

• matplotlib (≥3.10.5): Interactive plotting and GUI components
• numpy: Numerical computations and array operations
• ipython (≥9.4.0): Enhanced interactive capabilities

🎮 User Interface Guide

Main Display Panels

1. Input Complex Numbers: Shows current Gaussian integer inputs z₁ and z₂
2. XOR Result: Displays the result of z₁ ⊕ z₂ with optional trail visualization
3. Binary Representation: Shows base (-1+i) binary forms of inputs and result
4. Powers Spiral: Visualizes the geometric spiral of base (-1+i) powers
5. Transform Field: Vector field showing XOR transformation effects
6. Result History: Trajectory tracking of XOR results over time

Interactive Controls

• Sliders: Adjust real and imaginary parts of z₁ and z₂ (integer values only)
• Checkboxes: Toggle trail, vectors, grid, and power spiral displays
• Buttons: Reset, randomize, auto-rotate, and clear trail functions
• Presets: Quick access to mathematically interesting configurations

Exploration Tips

• Start with simple values like 1+i and i to understand basic patterns
• Use the auto-rotate feature to see continuous transformation patterns
• Enable trails to visualize how results change over parameter space
• Try preset patterns to explore specific mathematical relationships

🧮 Mathematical Examples

Basic XOR Operation

z₁ = 1+i  (binary: 1010 in base -1+i)
z₂ = i    (binary: 1100 in base -1+i)
Result = z₁ ⊕ z₂ = 1 (binary: 0110 in base -1+i)

Geometric Interpretation

XOR operations create non-linear transformations that:

• Mix high-order and low-order bit information
• Produce fractal-like patterns when animated
• Create unexpected symmetries and periodicities
• Bridge discrete mathematics and continuous geometry

📚 Development History

This project has evolved through several phases:

1. Initial Exploration (August 2025): Investigation of PCG algorithms led to complex XOR concepts
2. Prototype Development: Single-file implementation with basic visualization
3. Gaussian Integer Constraints: Enforcement of integer-only complex numbers for mathematical rigor
4. Documentation Pass: Comprehensive PEP 257 docstrings and type annotations
5. Modular Refactoring: Clean separation into math and GUI modules with proper packaging

See docs/PROJECT_JOURNAL.md for detailed development context and decision rationale.

🔬 Research Connections

This work intersects several mathematical domains:

• Number Theory: Gaussian integers and their arithmetic properties
• Complex Analysis: Geometric transformations in the complex plane
• Cryptography: Connections to pseudorandom number generation
• Discrete Mathematics: Binary representations and XOR operations
• Computational Geometry: Visualization of mathematical transformations

📖 References and Further Reading

• PCG Algorithm: Melissa O'Neill's 2014 paper "PCG: A Family of Simple Fast Space-Efficient Statistically Good Algorithms for Random Number Generation"
• Base (-1+i): Donald Knuth's "The Art of Computer Programming" discusses complex number bases
• Gaussian Integers: Any introductory algebraic number theory textbook
• XOR Operations: Fundamental to cryptography and error correction literature

🛠️ Development Guidelines

Code Style

• Type annotations: All functions and methods must have type hints
• Documentation: PEP 257 docstrings required for all public interfaces
• Testing: Use pytest for all test development (no unittest)
• Formatting: Ruff for code style consistency
• Dependencies: Managed via uv with locked versions

Project Structure

• Modular design: Clear separation between math and visualization
• Package organization: Proper src/ layout with clean imports
• Documentation: Maintain PROJECT_JOURNAL.md for context preservation
• Entry point: Standard main.py for uv run execution

🚧 Future Directions

Potential areas for expansion:

• 3D visualization of complex transformations
• Performance optimization for larger bit representations
• Additional number bases beyond (-1+i)
• Cryptographic applications of complex XOR operations
• Mathematical analysis tools for pattern recognition
• Export capabilities for research and publication

📄 License

[License information to be added]

🤝 Contributing

[Contribution guidelines to be added]

---

Note: This project represents an active mathematical exploration. The codebase is designed for research, experimentation, and educational purposes. The mathematical concepts are actively being developed and may lead to novel insights in number theory and cryptography.