matrix-toolkit 0.0.2

A comprehensive toolkit for sparse matrix management and test matrix generation

matrix-toolkit

matrix-toolkit is a Python library for fetching, managing, and converting sparse matrices from the SuiteSparse Matrix Collection, with built-in programmatic generation of structured test matrices (inspired by MATLAB's anymatrix). The project aims to provide a comprehensive set of structured matrices across a wide range of domains and to build an easy-to-use interface for matrix fetching and generation, used for benchmarking and testing numerical linear algebra algorithms and deep learning training.

Features

SuiteSparse Integration

• Smart Search & Filter: Search matrices by size, sparsity, symmetry, domain, and more
• Multi-Backend Support: Automatic conversion to SciPy, CuPy, JAX, PyTorch formats
• Flexible Storage: Save and load matrix collections with multiple formats (NPZ, HDF5, MAT)
• Dataset Management: Create reproducible matrix datasets with train/val/test splits
• Parallel Processing: Multi-threaded downloading and processing
• CLI Tools: Command-line interface for quick operations

Anymatrix Integration

• Test Matrix Generation: Programmatic generation of 40+ well-defined test matrices
• Property Verification: Automatic checking of mathematical properties
• Comprehensive Testing: Built-in test suite for all generated matrices
• Multiple Groups: Core, gallery, and custom matrix collections
• Unified Interface: Single API for both SuiteSparse and generated matrices

Installation

matrix-toolkit enables pip manager installation or simply github the repo for local deployment.

Basic Installation

pip install matrix-toolkit

With Optional Dependencies

# For CuPy support
pip install matrix-toolkit[cupy]

# For JAX support
pip install matrix-toolkit[jax]

# For PyTorch support
pip install matrix-toolkit[torch]

# Install all optional dependencies
pip install matrix-toolkit[all]

Development Installation

git clone https://github.com/inEXASCALE/matrix-toolkit.git
cd matrix-toolkit
pip install -e ".[dev]"

Quick Start

matrix-toolkit provides a comprehensive, easy-to-use interface for accessing matrices across diverse domains — ideal for benchmarking and testing numerical linear algebra algorithms and deep learning systems. The simple usage is as follows.

Basic Usage

from matrix_toolkit import MatrixFetcher

# Initialize fetcher
fetcher = MatrixFetcher()

# Search for matrices
matrices = fetcher.search(
    rows=(1000, 50000),
    sparsity=(0.8, 0.99),
    symmetry='symmetric'
)

# Fetch a specific matrix
matrix = fetcher.get_matrix(
    'HB/494_bus',
    backend='scipy',
    format='csr'
)

# Random sampling
sample = fetcher.fetch(
    n=10,
    mode='random',
    filters={'domain': 'physics'}
)

Dataset Creation

# Create a standardized dataset
dataset = fetcher.create_dataset(
    name='my_dataset',
    filters={
        'rows': (5000, 20000),
        'sparsity': (0.9, 0.99),
    },
    size=100,
    split={'train': 0.7, 'val': 0.15, 'test': 0.15}
)

# Save dataset
dataset.save('my_dataset')

# Load dataset
from matrix_toolkit.datasets import MatrixDataset
dataset = MatrixDataset.load('my_dataset')

Storage Management

# Save collection
fetcher.save_collection(
    matrices,
    path='/data/my_matrices',
    format='npz',
    compression=True
)

# Load collection
loaded = fetcher.load_collection('/data/my_matrices')

CLI Usage

# Search matrices
matrix-toolkit search --rows 1000:50000 --sparsity 0.9:0.99

# Fetch a matrix
matrix-toolkit fetch --name HB/494_bus --format csr --backend scipy

# List matrices by domain
matrix-toolkit list --domain physics

# Clear cache
matrix-toolkit cache --clear

# Create dataset
matrix-toolkit dataset create --config dataset.yaml

Anymatrix Test Matrices

from matrix_toolkit.anymatrix import AnyMatrix, MatrixProperties

# Initialize anymatrix
am = AnyMatrix()

# List available matrices
groups = am.groups()  # ['core', 'gallery']
matrices = am.list('core')  # List matrices in core group

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

# Check properties
assert MatrixProperties.is_symmetric(beta_matrix)
assert MatrixProperties.is_positive_definite(beta_matrix)

# Search for matrices with specific properties
symmetric_matrices = am.search(['symmetric', 'positive definite'])

Unified Interface

from matrix_toolkit import UnifiedMatrixCollection

mc = UnifiedMatrixCollection()

# Get from anymatrix
A = mc.get('anymatrix/core/beta', 10)

# Get from SuiteSparse
B = mc.get('suitesparse/HB/494_bus', backend='scipy')

# Search both collections
results = mc.search(properties=['symmetric'])

# Verify properties automatically
mc.verify_properties('anymatrix/core/beta', 10, verbose=True)

Available Anymatrix Collections

Core Group

• beta - Symmetric positive definite matrix
• fourier - Discrete Fourier transform matrix (unitary)
• nilpot_triang - Nilpotent upper triangular
• nilpot_tridiag - Nilpotent tridiagonal
• vand - Vandermonde matrix
• circul_binom - Circulant with binomial coefficients
• stoch_cesaro - Stochastic Cesaro matrix
• tournament - Random tournament matrix
• perfect_shuffle - Perfect shuffle permutation
• collatz - Collatz conjecture matrix
• And more...

Gallery Group

• lehmer - Lehmer matrix (symmetric positive definite)
• minij - MIN(i,j) matrix
• moler - Moler matrix
• pei - Pei matrix
• clement - Clement tridiagonal
• kms - Kac-Murdock-Szego Toeplitz matrix

Running Tests

Test all anymatrix matrices

python examples/run_anymatrix_tests.py --verbose --report test_report.txt

Test specific groups

python examples/run_anymatrix_tests.py --groups core gallery

Python API

from matrix_toolkit.anymatrix.testing import run_all_tests

results = run_all_tests(verbose=True, generate_report=True)

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

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