MatrixGen#

PyPI Status Python Version License

Read the documentation at https://matrixgen.readthedocs.io/ Tests Codecov

pre-commit Black

Overview#

  • MatrixGen is a modular Python package for generating, resizing, and analyzing sparse matrices. It supports multiple synthesis methods and provides tools for structure-aware scaling, useful in scientific computing, numerical simulations, and ML workloads where realistic matrix patterns are essential.

Features#

  • Modular Sparse Matrix Generation Generate structurally realistic sparse matrices of arbitrary size from a given base matrix using a unified and extensible framework.

  • Multiple Scaling Techniques Includes support for adapted resizing methods such as:

    • Nearest Neighbor

    • Bilinear Interpolation

    • Lanczos Resampling

    • Discrete Fourier Transform (DFT)

    • Discrete Cosine Transform (DCT)

    • Wavelet Transforms

  • Preservation of Structure and Sparsity Each method is designed to maintain key structural properties including sparsity patterns, symmetry, and bandwidth.

  • Controlled Randomization Allows slight variations during generation to support realistic data augmentation while retaining essential characteristics.

  • Feature-Based Evaluation Measures similarity between original and synthetic matrices using structural features like:

    • Nonzero density

    • Bandwidth and profile

    • Symmetry (Psym)

    • Diagonal spread and entropy

    • Row/column distribution metrics

    Cosine similarity is used to quantify structural preservation.

  • Scalable Generation Capable of generating matrices at much larger scales than the input while preserving core traits — useful for performance benchmarking and large-scale ML testing.

  • Fills a Sparse Matrix Data Gap Addresses the lack of diverse, realistic sparse matrices for algorithm validation, benchmarking, and ML applications.

Requirements#

  • Handled automatically via Poetry. Requires Python 3.11 or higher.

Installation#

You can install MatrixGen via pip from PyPI:

$ pip install matrixgen

Usage#

You can use MatrixGen via:

  • Python API: from matrixgen import RESIZE_METHODS, resize_matrix, load_matrix, save_matrix

  • Command Line: Run matrixgen --help to see options

  • See the examples/ folder for usage patterns.

Contributing#

Contributions are very welcome. To learn more, see the Contributor Guide.

License#

Distributed under the terms of the Apache 2.0 license, MatrixGen is free and open source software.

Issues#

If you encounter any problems, please file an issue along with a detailed description.

Credits#

This project was generated from @cjolowicz’s Hypermodern Python Cookiecutter template.

This project is based off of MatGen-d which in itself is a fork of the original MatGen by Ali Emre Pamuk, Mert Altekin, and Faruk Kaplan. They are the original creators of the matrix synthesis/generation/resizing logic and without them, this project wouldn’t exist.