Matrix Toolkit¶

A Comprehensive Python Framework for Sparse Matrix Generation & PDE Discretization

2800+ Real-World Matrices

🗂️ SuiteSparse Collection

Smart search & filtering by size, sparsity, symmetry, and domain. Multi-threaded download with automatic caching.

Search Filter Cache

user_guide/suitesparse

65+ Test Matrices

🧪 Anymatrix Test Suite

Well-defined matrices with automatic property verification. 5 collections: Core, Gallery, Hadamard, MATLAB, Regtools.

Verified Properties Testing

Working with Anymatrix

17 PDE Equation Types

📐 PDE Discretization

Classical, fluids, solids, EM, quantum mechanics. 1D/2D/3D support with multiple discretization schemes.

1D 2D 3D

PDE Matrix Generation

🚀 Multi-Backend Support

Automatic conversion to SciPy, NumPy, CuPy, JAX, PyTorch

user_guide/converters

📊 Dataset Management

Train/val/test splits with stratified & diversity sampling

user_guide/datasets

🎲 Random Parameter Sampling

Uniform, Normal, Log-normal, Latin Hypercube Sampling

tutorials/pde_tutorial

💾 Flexible Storage

NPZ, HDF5, MAT, MTX formats with metadata preservation

user_guide/storage

Quick Start¶

Installation

pip install matrix-toolkit

Or install with all extras:

pip install matrix-toolkit[all]

🗂️ SuiteSparse

from matrix_toolkit import MatrixFetcher

# Initialize and search
fetcher = MatrixFetcher()
results = fetcher.search(
    rows=(1000, 50000),
    sparsity=(0.8, 0.99),
    symmetry='symmetric'
)

# Fetch matrix
A = fetcher.get_matrix('HB/494_bus', backend='scipy')

🧪 Anymatrix

from matrix_toolkit.anymatrix import AnyMatrix, MatrixProperties

am = AnyMatrix()

# Generate test matrix
beta = am.generate('core/beta', 10)

# Verify properties
assert MatrixProperties.is_symmetric(beta)
assert MatrixProperties.is_positive_definite(beta)

📐 PDE Matrix

from matrix_toolkit.pde import PDEMatrixGenerator, PDEConfig

# 2D Poisson equation
config = PDEConfig(dimension=2, mesh_size=64)
gen = PDEMatrixGenerator('poisson', config)
A = gen.generate()

print(f"Shape: {A.shape}, Sparsity: 99.88%")

🚀 GPU Support

config = PDEConfig(
    dimension=3,
    mesh_size=32,
    backend='cupy',  # GPU acceleration
    format='csr'
)

gen = PDEMatrixGenerator('helmholtz', config)
A_gpu = gen.generate()  # Matrix on GPU!

Features Overview¶

🧪 Anymatrix Test Matrices

65+ Test Matrices Across 5 Collections

Group	Count	Description
Core	45+	Beta, Fourier, Wilson, Nilpotent, Stochastic, Structured
Gallery	6	Lehmer, Minij, Moler, Clement, KMS, Tridiag
Hadamard	2	Hadamard, Walsh orthogonal matrices
MATLAB	8	Magic, Pascal, Hilbert, Rosser, Wilkinson
Regtools	5	Shaw, Phillips, Deriv2, Gravity, Blur (ill-posed problems)

Property Verification (20+ Properties)

Symmetry, Hermitian, Skew-symmetric
Positive definite, Positive semi-definite
Orthogonal, Unitary
Diagonal, Tridiagonal, Triangular
Toeplitz, Circulant, Hankel
Stochastic (row, column, doubly)

Performance & Scalability¶

1D Problems

10,000 points

Matrix: 10,000²

NNZ: ~30K

Sparsity: 99.97%

2D Problems

100×100 grid

Matrix: 10,000²

NNZ: ~50K

Sparsity: 99.95%

3D Problems

50×50×50 grid

Matrix: 125,000²

NNZ: ~875K

Sparsity: 99.99%

Documentation Contents¶

📖 User Guide

Comprehensive guides for all modules and features

user_guide/index

🎓 Tutorials

Step-by-step tutorials for common workflows

tutorials/index

💡 Examples

Advanced examples and use cases

examples/advanced_examples

📚 API Reference

Complete API documentation

api/index

Poisson	`-∇²u = f`	1D/2D/3D
Heat	`∂u/∂t = α∇²u`	1D/2D/3D
Wave	`∂²u/∂t² = c²∇²u`	1D/2D/3D
Helmholtz	`-∇²u - k²u = f`	1D/2D/3D
Biharmonic	`∇⁴u = f`	1D/2D/3D

Stokes	`-μ∇²u + ∇p = f`, `∇·u = 0`	2D/3D
Navier-Stokes	Linearized NS equations	2D/3D
Burgers	`∂u/∂t + u∂u/∂x = ν∇²u`	1D/2D
Advection-Diff	`∂T/∂t + u·∇T = α∇²T`	1D/2D/3D

Elasticity	`-∇·σ(u) = f`	2D/3D
Maxwell	`∇×(∇×E) - ω²με E`	3D
Schrödinger	`iℏ∂ψ/∂t = Ĥψ`	1D/2D/3D
Klein-Gordon	`∂²φ/∂t² - c²∇²φ + m²φ`	1D/2D/3D