matrix-toolkit 0.0.1__tar.gz

matrix_toolkit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 inEXASCALE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matrix_toolkit-0.0.1/PKG-INFO

@@ -0,0 +1,303 @@
+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}
+}
+```

matrix_toolkit-0.0.1/README.md

@@ -0,0 +1,247 @@
+# 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}
+}
+```

matrix_toolkit-0.0.1/matrix_toolkit/__init__.py

@@ -0,0 +1,24 @@
+"""
+Matrix Toolkit - A comprehensive toolkit for sparse matrix management
+"""
+
+__version__ = "0.0.1"
+__author__ = "Xinye Chen"
+__email__ = "xinyechenai@gmail.com"
+
+from matrix_toolkit.core.fetcher import MatrixFetcher
+from matrix_toolkit.core.search import MatrixSearcher
+from matrix_toolkit.datasets.dataset import MatrixDataset
+from matrix_toolkit.core.config import Config
+
+# Anymatrix integration
+from matrix_toolkit.anymatrix import AnyMatrix, MatrixProperties
+
+__all__ = [
+    "MatrixFetcher",
+    "MatrixSearcher",
+    "MatrixDataset",
+    "Config",
+    "AnyMatrix",
+    "MatrixProperties",
+]

matrix_toolkit-0.0.1/matrix_toolkit/anymatrix/__init__.py

@@ -0,0 +1,21 @@
+"""
+Anymatrix integration - A collection of test matrices inspired by the 
+MATLAB anymatrix toolbox by Higham and Mikaitis.
+
+This module provides programmatic generation of various test matrices
+with well-defined properties for numerical computing research.
+"""
+
+from matrix_toolkit.anymatrix.registry import AnyMatrix
+from matrix_toolkit.anymatrix.properties import MatrixProperties
+
+__all__ = ["AnyMatrix", "MatrixProperties"]
+
+# Version info
+__version__ = "0.1.0"
+__anymatrix_reference__ = """
+Nicholas J. Higham and Mantas Mikaitis. 
+Anymatrix: An Extendable MATLAB Matrix Collection. 
+Numer. Algorithms, 90:3, 1175-1196, Dec. 2021.
+DOI: 10.1007/s11075-021-01226-2
+"""

matrix_toolkit-0.0.1/matrix_toolkit/anymatrix/groups/__init__.py

@@ -0,0 +1,3 @@
+"""Matrix generator groups"""
+
+__all__ = []