Quick Start Guide¶

This guide will get you up and running with Matrix Toolkit in minutes.

Basic Concepts¶

Matrix Toolkit provides two main ways to work with matrices:

SuiteSparse Collection: Download real-world sparse matrices from the SuiteSparse repository
Anymatrix: Programmatically generate test matrices with known properties

SuiteSparse Basics¶

Initialize the Fetcher¶

from matrix_toolkit import MatrixFetcher

fetcher = MatrixFetcher()

Search for Matrices¶

# Search by size
results = fetcher.search(rows=(1000, 10000))

# Search by multiple criteria
results = fetcher.search(
    rows=(1000, 50000),
    sparsity=(0.8, 0.99),
    symmetry='symmetric'
)

# View results
print(results.head())

Fetch a Matrix¶

# Fetch a specific matrix
matrix = fetcher.get_matrix('HB/494_bus')

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

print(f"Shape: {matrix.shape}")
print(f"Non-zeros: {matrix.nnz}")

Anymatrix Basics¶

Initialize Anymatrix¶

from matrix_toolkit.anymatrix import AnyMatrix

am = AnyMatrix()

List Available Matrices¶

# List all groups
groups = am.groups()
print(groups)  # ['core', 'gallery', 'hadamard', 'matlab', 'regtools']

# List matrices in a group
core_matrices = am.list('core')
print(core_matrices[:10])

Generate Matrices¶

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

# Generate a Fourier matrix
fourier = am.generate('core/fourier', 8)

# Generate a Hilbert matrix
hilbert = am.generate('matlab/hilbert', 5)

Check Properties¶

from matrix_toolkit.anymatrix import MatrixProperties

# Check individual properties
is_sym = MatrixProperties.is_symmetric(beta)
is_pd = MatrixProperties.is_positive_definite(beta)

print(f"Symmetric: {is_sym}")
print(f"Positive Definite: {is_pd}")

# Check multiple properties at once
props = ['symmetric', 'positive definite']
results = MatrixProperties.check_properties(beta, props)
print(results)

Search by Properties¶

# Find all symmetric matrices
symmetric = am.search(['symmetric'])

# Find symmetric AND positive definite matrices
sym_pd = am.search(['symmetric', 'positive definite'])

print(f"Found {len(sym_pd)} matrices:")
for matrix_id in sym_pd[:5]:
    print(f"  - {matrix_id}")

Get Help¶

# Get help for a specific matrix
help_text = am.help('core/beta')
print(help_text)

Working with Datasets¶

Create a Dataset¶

# Create a dataset from search results
dataset = fetcher.create_dataset(
    name='physics_matrices',
    filters={
        'domain': 'physics',
        'rows': (1000, 10000),
        'sparsity': (0.9, 0.99)
    },
    size=50,
    split={'train': 0.7, 'val': 0.15, 'test': 0.15}
)

print(f"Dataset: {dataset.name}")
print(f"Total: {len(dataset)}")
print(f"Splits: {list(dataset.splits.keys())}")

Save and Load Datasets¶

# Save dataset
dataset.save('my_datasets/physics')

# Load dataset
from matrix_toolkit.datasets import MatrixDataset
loaded = MatrixDataset.load('my_datasets/physics')

Backend Conversion¶

Convert to Different Backends¶

from matrix_toolkit.converters import ConverterFactory

# Get a matrix
matrix = am.generate('core/beta', 100)

# Convert to different SciPy formats
scipy_converter = ConverterFactory.get_converter('scipy')
csr = scipy_converter.convert(matrix, format='csr')
csc = scipy_converter.convert(matrix, format='csc')

# Convert to NumPy dense
numpy_converter = ConverterFactory.get_converter('numpy')
dense = numpy_converter.convert(matrix, format='dense')

# Convert to CuPy (if available)
try:
    cupy_converter = ConverterFactory.get_converter('cupy')
    gpu_matrix = cupy_converter.convert(matrix, format='csr')
    print("Matrix is now on GPU!")
except ImportError:
    print("CuPy not available")

Unified Interface¶

Access Both Collections¶

from matrix_toolkit import UnifiedMatrixCollection

mc = UnifiedMatrixCollection()

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

# Get from SuiteSparse (when available)
B = mc.get('suitesparse/HB/494_bus')

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

Command-Line Interface¶

Matrix Toolkit also provides a CLI:

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

# List matrices
matrix-toolkit list --group core

# Fetch a matrix
matrix-toolkit fetch --name HB/494_bus --output ./matrices

# Anymatrix tests
python examples/run_anymatrix_tests.py --verbose

Next Steps¶

Read the user_guide/index for detailed documentation
Check out examples/index for more examples
Learn about Matrix Properties for property testing
See api/index for complete API reference

Complete Example¶

Here’s a complete example combining multiple features:

from matrix_toolkit import MatrixFetcher, UnifiedMatrixCollection
from matrix_toolkit.anymatrix import AnyMatrix, MatrixProperties

# Initialize
am = AnyMatrix()
mc = UnifiedMatrixCollection()

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

# Verify properties
props = am.properties('core/beta')
results = MatrixProperties.check_properties(test_matrix, props)

print("Property Verification:")
for prop, passed in results.items():
    status = "✓" if passed else "✗"
    print(f"  {status} {prop}")

# Search for similar matrices
similar = am.search(['symmetric', 'positive definite'])
print(f"\nFound {len(similar)} similar matrices")

# Save matrix
import scipy.sparse as sp
sp.save_npz('my_matrix.npz', test_matrix)
print("\nMatrix saved to my_matrix.npz")