Metadata-Version: 2.4
Name: matrix-toolkit
Version: 0.0.1
Summary: A comprehensive toolkit for sparse matrix management and test matrix generation
Author: PAPA
Author-email: Xinye Chen <xinyechenai@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/matrix-toolkit
Project-URL: Documentation, https://matrix-toolkit.readthedocs.io
Project-URL: Repository, https://github.com/yourusername/matrix-toolkit
Project-URL: Issues, https://github.com/yourusername/matrix-toolkit/issues
Keywords: sparse-matrix,suitesparse,anymatrix,test-matrices,scientific-computing,numerical-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: requests>=2.25.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: click>=8.0.0
Requires-Dist: joblib>=1.0.0
Requires-Dist: h5py>=3.0.0
Provides-Extra: cupy
Requires-Dist: cupy>=10.0.0; extra == "cupy"
Provides-Extra: jax
Requires-Dist: jax>=0.3.0; extra == "jax"
Requires-Dist: jaxlib>=0.3.0; extra == "jax"
Provides-Extra: torch
Requires-Dist: torch>=1.9.0; extra == "torch"
Provides-Extra: all
Requires-Dist: cupy>=10.0.0; extra == "all"
Requires-Dist: jax>=0.3.0; extra == "all"
Requires-Dist: jaxlib>=0.3.0; extra == "all"
Requires-Dist: torch>=1.9.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: sphinx>=4.5.0; extra == "dev"
Dynamic: license-file

# matrix-toolkit



A comprehensive Python toolkit for fetching, managing, and converting sparse matrices from the SuiteSparse Matrix Collection, plus programmatic generation of test matrices inspired by MATLAB's anymatrix.

## 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

### Basic Installation
```bash
pip install matrix-toolkit
```

### With Optional Dependencies
```bash
# 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
```bash
git clone https://github.com/inEXASCALE/matrix-toolkit.git
cd matrix-toolkit
pip install -e ".[dev]"
```

## Quick Start

### Basic Usage

```python
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

```python
# 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

```python
# 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

```bash
# 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

```python
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

```python
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
```bash
python examples/run_anymatrix_tests.py --verbose --report test_report.txt
```

### Test specific groups
```bash
python examples/run_anymatrix_tests.py --groups core gallery
```

### Python API
```python
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](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use this toolkit in your research, please cite:

```bibtex
@software{matrix_toolkit,
  title={Matrix Toolkit: A Python Package for Sparse Matrix Management},
  author={Xinye Chen},
  year={2024},
  url={https://github.com/chenxinye/matrix-toolkit}
}
```
