pdevisualizer 1.0.0

A lightweight, high-performance Python library for prototyping and visualizing 2D/3D partial differential equations

PDEVisualizer

A lightweight Python library for prototyping and visualizing 2D partial differential equations (PDEs). Built for scientific computing applications with performance optimization and beautiful visualizations.

🚀 Features

• 2D Heat Equation Solver: Finite difference implementation with stability validation
• 2D Wave Equation Solver: Leapfrog scheme with CFL condition enforcement
• Numba JIT Compilation: Near-C++ performance for numerical computations
• Beautiful Animations: Publication-quality visualizations with matplotlib
• Comprehensive Testing: 23 test cases ensuring mathematical correctness
• Professional Packaging: Easy installation and distribution

📊 Supported Equations

Heat Equation (Parabolic PDE)

∂u/∂t = α∇²u

Models heat diffusion, chemical concentration, and other diffusive processes.

Wave Equation (Hyperbolic PDE)

∂²u/∂t² = c²∇²u

Models sound waves, electromagnetic waves, and mechanical vibrations.

🛠️ Installation

Prerequisites

• Python 3.8+
• NumPy, Matplotlib, Numba, SciPy

Install from Source

git clone https://github.com/yourusername/pdevisualizer.git
cd pdevisualizer
pip install -e .

Verify Installation

pytest tests/ -v

Expected: 23 tests passed

📖 Quick Start

Heat Diffusion

import numpy as np
from pdevisualizer.heat2d import solve_heat, animate_heat

# Create initial temperature field with hot spot
grid_size = 100
u0 = np.zeros((grid_size, grid_size))
u0[50, 50] = 100  # Hot spot at center

# Solve heat equation
u_final = solve_heat(u0, α=0.25, dt=0.1, dx=1.0, dy=1.0, steps=100)

# Create animation
anim = animate_heat(u0, α=0.25, dt=0.1, frames=200)
anim.save("heat_diffusion.gif", writer="pillow")

Wave Propagation

from pdevisualizer.wave2d import solve_wave, animate_wave, create_gaussian_pulse

# Create Gaussian pulse initial condition
grid_size = 100
u0 = create_gaussian_pulse(grid_size, center=(50, 50), sigma=5, amplitude=2.0)

# Solve wave equation
u_final = solve_wave(u0, c=1.0, dt=0.05, dx=1.0, dy=1.0, steps=200)

# Create animation
anim = animate_wave(u0, c=1.0, dt=0.05, frames=200)
anim.save("wave_propagation.gif", writer="pillow")

🔬 Example Visualizations

Heat Diffusion

Heat spreads smoothly from a central hot spot, demonstrating diffusive behavior characteristic of parabolic PDEs.

[Heat diffusion animation would be embedded here]

Wave Propagation - Gaussian Pulse

A Gaussian pulse propagates outward with sharp wave fronts, showing the oscillatory nature of hyperbolic PDEs.

[Gaussian wave animation would be embedded here]

Wave Propagation - Circular Wave

Circular wave fronts expand outward, demonstrating wave interference and propagation patterns.

[Circular wave animation would be embedded here]

🧪 Testing

Run the comprehensive test suite:

# Run all tests
pytest tests/ -v

# Run specific equation tests
pytest tests/test_heat2d.py -v    # 9 tests for heat equation
pytest tests/test_wave2d.py -v    # 14 tests for wave equation

# Run with coverage
pytest tests/ --cov=pdevisualizer

Test Coverage

• Mathematical Correctness: Validates PDE solutions against known behaviors
• Numerical Stability: Ensures stability conditions are enforced
• Boundary Conditions: Verifies proper boundary handling
• Physical Properties: Tests energy conservation and wave propagation
• Performance: Validates Numba compilation and optimization

⚡ Performance

Optimization Features

• Numba JIT: Just-in-time compilation for computational kernels
• Vectorized Operations: NumPy array operations for efficiency
• Memory Management: Efficient array copying and reuse
• Stability Validation: Prevents numerical instabilities

Benchmarks

• 100×100 grid: ~0.1s per 100 time steps
• 500×500 grid: ~2s per 100 time steps
• 1000×1000 grid: ~15s per 100 time steps

Benchmarks on Apple M2 MacBook Air with Python 3.12

🔧 API Reference

Heat Equation

solve_heat(u0, α=1.0, dt=0.1, dx=1.0, dy=1.0, steps=100)
animate_heat(u0, α=1.0, dt=0.1, dx=1.0, dy=1.0, frames=100, interval=50)

Wave Equation

solve_wave(u0, v0=None, c=1.0, dt=0.1, dx=1.0, dy=1.0, steps=100)
animate_wave(u0, v0=None, c=1.0, dt=0.1, dx=1.0, dy=1.0, frames=100, interval=50)

# Helper functions
create_gaussian_pulse(grid_size, center, sigma, amplitude=1.0)
create_circular_wave(grid_size, center, radius, amplitude=1.0)

Parameters

• u0: Initial field (2D numpy array)
• v0: Initial velocity for wave equation (2D numpy array, optional)
• α: Thermal diffusivity for heat equation
• c: Wave speed for wave equation
• dt: Time step size
• dx, dy: Spatial grid spacing
• steps: Number of time steps to solve
• frames: Number of animation frames

🛡️ Stability Conditions

Heat Equation

For numerical stability: α * dt * (1/dx² + 1/dy²) ≤ 0.5

Wave Equation

For numerical stability (CFL condition): c * dt * √(1/dx² + 1/dy²) ≤ 1.0

Both solvers automatically validate these conditions and raise errors for unstable parameters.

🗺️ Roadmap

Phase 1: Core Solvers ✅

• Heat equation implementation
• Wave equation implementation
• Comprehensive testing
• Performance optimization
• Basic visualizations

Phase 2: Advanced Features (In Progress)

• Flexible boundary conditions (Dirichlet, Neumann, periodic)
• Multiple initial condition types
• Interactive parameter exploration
• Jupyter notebook demos
• Enhanced documentation

Phase 3: Extended Capabilities (Future)

• 3D equation support
• Additional PDE types (Schrödinger, diffusion-reaction)
• GPU acceleration with CuPy
• Interactive web interface
• Real-time parameter adjustment

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Development Setup

git clone https://github.com/yourusername/pdevisualizer.git
cd pdevisualizer
pip install -e ".[dev]"
pytest tests/

Code Style

• Follow PEP 8 guidelines
• Use type hints where appropriate
• Add comprehensive tests for new features
• Document all public functions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏆 Acknowledgments

• NumPy/SciPy: Foundation for numerical computing
• Numba: JIT compilation for performance
• Matplotlib: Beautiful scientific visualizations
• Pytest: Comprehensive testing framework

📧 Contact

For questions, suggestions, or collaboration opportunities, please open an issue on GitHub.

---

Built with ❤️ for the scientific computing community